Style Guide

To make this documentation easier for users, the style of articles should be consistent and clear. The following guidelines are best practices and strong suggestions. Text found to not be following these Language Style/Grammar guidelines may be edited and corrected at any time.

See also

See Documentation Quality Guidelines for information about how entries in the documentation should be written and what they should contain.

Trademarks

  • The first use of pfSense® must have the ® symbol on each and every page.

  • Trademarks, such as “pfSense®”, are proper adjectives and not verbs or nouns.

    In most cases this means that a reference must be phrased as “pfSense® software” instead of “pfSense®” on its own.

  • Include “Plus” or “CE” when referring to specific builds of pfSense software. If a topic applies to any build, then this extra reference is not necessary.

    Example: “pfSense® Plus software”, “pfSense® CE software”

  • Be respectful of Trademarks, including those of third parties.

  • Where feasible, try to include relevant marks for third parties or use their preferred nomenclature, phrasing, formatting, and so on.

    For example, use “Proxmox® VE” and not “Proxmox” when referring to the Proxmox Virtualization Environment as that is the way Proxmox Server Solutions GmbH prefers others to reference the product.

Examples:

Firewalls:

  • Good: Firewall running pfSense® software

  • Bad: pfSense® firewall, pfSense® box

Versions:

  • Good: pfSense® Plus software version 23.01

  • Bad: pfSense® 23.01

Installations:

  • Good: Installation of pfSense® software

  • Bad: pfSense® install

Referring to items involving pfSense software

Refer to a firewall running pfSense as a “firewall” or “node”. Avoid other similar terms (“router”, “system”, “box”, etc.) for clarity and consistency.

Capitalization

Capitalize terms correctly! Especially pfSense!

No other capitalization of “pfSense” may be used except in a URL which is acceptable as lowercase (e.g. https://www.pfsense.org ). If a sentence begins with “pfSense” the first letter must remain lowercase.

Note

If any other usage of “pfSense” or a misspelling of same is present in a document (“PFsense”, “PFSense”, “pfSence”, etc), fix it immediately.

Other special notes for capitalization:

  • WebGUI, IPsec, OpenVPN, Internet, Ethernet, VPN, DNS, PPPoE, IPv4, IPv6, NPt, strongSwan, pfsync, pftop, JavaScript, WireGuard.

What to Avoid

Avoid addressing the user directly (“you”, “your”, etc.):

Rewrite sentences to avoid addressing the user when found. Exceptions may be made for quoted/cited text or other unavoidable circumstances.

Avoid references to the writer (“I”, “we”):

Except when making specific recommendations, which is OK to avoid using passive voice. “We recommend” is better than “It is recommended”, though the ideal phrasing would be “the best practice is”.

Avoid the use of words such as “should”, “could”, “might”:

Words that do not commit to a specific action/result are undesirable. For example “This should happen” or “That might appear”. Some instances are expected/required when making recommendations, but reword where feasible.

Avoid the use of Weasel words:

See Weasel Words for reference.

Avoid redundant phrases:

This especially includes acronym references that duplicate words: “WAN Network”, “LAN Network”, “DUID Identifier”, “6RD Rapid Deployment”. Remove the redundant word(s) and/or use alternate phrasing (“WAN Subnet” or “Network on the WAN interface” rather than “WAN Network”)

Avoid unnecessary abbreviations and shortening of words:

This creates ambiguity, for example:

  • Avoid using “IP” or “IPs” to refer to IP addresses. Use the full form “IP address” instead to remove ambiguity.

  • Avoid using “config” when “config.xml” or “configuration” is more clear.

  • Avoid using “ovpn” to mean “OpenVPN” except in cases when the OS-level interfaces are being referenced (ovpncX is OK, “Use OVPN instead” is not.)

Avoid using “here” for links:

Do not make links for “here”, “click here”, or similar phrasing. They provide no context for the link, cause redundancy in phrasing, and cause problems for users that require accessibility functions such as screen readers.

See also

See recommendations from W3C Tips and uxmovement.

Avoid awkward possessive references:

For example: “firewall’s”, “pfSense’s”.

Avoid gender-specific pronouns:

Example: “his”, “hers”

Avoid leaving out necessary hyphens:

Example: “howto” should be “how-to”

Avoid “Britishisms” or other non-en_US style spellings:

Use “Flavor”, not “Flavour”. Use “Specialize”, not “Specialise”

Avoid confusing bandwidth specifications:

  • Avoid confusing bits and bytes. Use Big B for bytes, little b for bits.

  • Avoid ambiguity when specifying bandwidth measurements. Bandwidth should always have time component, such as per second. “5 Mbit/s” is much clearer than “5 Mbps”, “5 Mb”, or “5MB”.

Avoid passive voice when necessary:

When it makes more sense to do so, try to make it clear who is taking an action in a sentence, and use active voice instead of passive voice where possible in these cases.

  • Bad: “When a packet is routed”

  • Okay: “When a packet is routed by the firewall”

  • Better: “When the firewall routes a packet”

There are times when the person or item taking an action isn’t as important as the receiver of the action. The performer of the action may be unknown, assumed, or unimportant. In these cases the passive voice is acceptible. For example when describing GUI interactions, “When X is clicked” may be less awkward than repeating “When the user clicks X”.

Crafting Instructions

When forming lists of instructions, start each item with an action word when possible: Click x, Select x, Enter x, Navigate to x.

When instructing a user to reach a specific page or place in the GUI, reference this action as “Navigate to”.

Example Text

When offering examples, keep the following in mind:

  • Domain names should use example.com or another reserved name from RFC 2606.

  • IP address examples should be taken from subnets reserved for documentation in RFC 6890: 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24 or the traditional RFC 1918 networks 192.168.0.0/16, 172.16.0.0/12, or 10.0.0.0/8 if the documentation subnets are not sufficient.

    • In some cases where additional unique examples are needed, use the benchmarking subnet 198.18.0.0/15.

High Availability / CARP References

  • Refer to the cluster as a “High Availability Cluster” or “HA Cluster” and not as a “CARP Cluster”.

  • Use the term “node” as in “cluster node” for referencing an individual unit.

  • Use the term “primary” for the primary node, never “master” as this can be confused with the CARP VIP status.

  • Use the term “secondary” for the secondary node, never “backup” or “slave” as this is outdated terminology and can be confused with the CARP VIP status.

  • Use the terms “Sync interface” or “Interconnect interface” when referring to the dedicated interface between HA Cluster nodes. Never refer to that interface as a “CARP interface”.