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 articles. Especially in How-To articles.
Do not start a how-to with installing pfSense or performing 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 confusing copies of the same information. Keep How-To articles as concise as possible!
Where to see why an article was flagged¶
Articles flagged for cleanup should have corresponding comments on the source of the article at GitHub, or issues on GitHub discussing what’s wrong with them.