Documentation Quality Guidelines¶
Overview¶
This document aims to give an idea of what types of information should be in articles to keep them as useful as possible for other users of the documentation.
For information about style and formatting, see Style Guide.
What to include in articles¶
Concise, detailed information – the more accurate the information, the more useful it is.
Good spelling and grammar
Good formatting (Style Guide)
Proper categories to classify the article. For example, place the new article in the correct area of the documentation site (e.g. articles about OpenVPN go under
source/vpn/openvpn/).
What not to include in articles¶
Poor grammar
Inconsistent or poor backing data
Disparaging comments
Ambiguity – try to make articles clear so there is no confusion
Avoid creating a new directory or category for a single article if possible. If more will be added, then it is OK.
Redundant information already covered in other documents. Especially in recipes.
Do not start a recipe with installing pfSense software or other basic tasks. Make assumptions and link to other articles for topics already covered elsewhere. There is no need to reinvent the wheel and have multiple overlapping copies of the same information. This helps keep recipes as concise as possible!
Where to see why an article was flagged¶
Articles flagged for cleanup should have corresponding issues on GitHub discussing the required changes.