To make this documentation easier for users, we prefer to have the style of
articles be consistent and clear. The following guidelines are strongly
suggested. Text found to not be following these Language Style/Grammar
guidelines may be edited and corrected at any time.

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.

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

Rewrite sentences to avoid this usage 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”.

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 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 recommendations from W3C Tips and
uxmovement.

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.

For assistance in solving software problems, please post your question on the Netgate Forum.
If you see anything that's wrong or missing with the documentation, please suggest an edit by using the feedback
button in the upper right corner so it can be improved.