• All Documentation
• Roles
• Projects

0. Must be written in Markdown.
1. Must begin with an H1 header of the form <TOPIC> Index, where <TOPIC> is the topic, usually not the same as the name, of the page. Beneath that header there must be an index, with links to each header in the document.
2. In lieu of a normal directory structure, pages are disambiguated into categories by prefixes. The page you're currently reading, for example, falls under the guidelines category, and covers documentation, so it is named guidelines-documentation. However, its topic is "Documentation Guidelines". The name and topic do not need to share the same words, but the name should reflect the topic in a meaningful way.
3. Sentences should be grammatically correct and proofread (so, reread from start to finish before submission) for grammar, spelling, and logic errors.
4. Use of abbreviations is permitted for common proper names in computing (SaaS, SMTP, TCP, IP, NNTP, NTP, SSH, etc.), but not for informal phrases (FUBAR, SNAFU, PEBKAC, YOLO, etc.).
5. Language should be overwhelmingly formal, although very occasional and brief jokes are allowed. When a joke is made, it should never make reference to any topic a reasonable person would be uncomfortable with their five-year-old hearing.
6. The reader is assumed to be familiar with Ansible, Python, and programming in general. An author may assume the reader has taken at least an introductory college-level course in computer science, and is familiar with common data structures, algorithms, programming paradigms / patterns. It is also safe to assume the reader is familiar with common system administration tasks and tools (cron, logrotate, yum, apt, bash, ip).
7. When someone expresses unfamiliarity with a given process or technology mentioned on a given wiki page, if at least one in four of the people who participate in subsequent discussion were not familiar with the process or technology at the time the ticket was created, the referenced documentation must be updated to (at minimum) include a link to more information about the process or technology.

In other words...

• if someone has no idea what a DNS server is, and
• DNS servers are mentioned in the wiki page for the bind role, and
• that confused person opens up an issue ticket to ask about the bind role's wiki page, and
• in the comment discussion on the issue ticket, at least one in four of the commenters didn't know what a DNS server was when the ticket was created, then
• the bind role wiki page must be edited, and the first reference to DNS on that page must be turned into a link which points to more information about DNS.

8. Provide examples! When you provide concrete example code / example scenarios abstract ideas are often far easier to understand.
9. Diagrams and images are permitted and encouraged. Not every article needs them, and their presence is certainly not a requirement, but keep them in mind. For showing dependencies, relationships between machines / roles, timelines, and control flow, they are especially useful.
10. Rules which apply to numbers do not apply to numbers used in code examples; it should be possible to unambiguously infer numeric base and other characteristics of a number from its representation within the code (via the same means used by the lexer for that language).
11. Nonnegative integers lower than 10 should be written out in words (e.g. one, nine, four, zero), all other base-10 numbers should be written using decimal points and Arabic numerals (e.g. -3, 0.2, 14, -19, -0.2).
12. When writing out hexadecimal numbers, prefix them with 0x. They may be upper- or lowercase, but lowercase is preferred.
13. Octal numbers are indicated by prefixing them with 0.
14. Binary numbers are indicated by indicating that they are binary in the surrounding text.
15. Unless explicitly designated otherwise by one of the means stated above, all numbers are assumed to be normal decimal numbers.
16. Links must be reference-style links, and the list of reference-to-link mappings should be at the end of the document (to make it easy to find, modify). That list of mappings at the end of the document should be preceded by an HTML comment line, <!-- bibliography -->, with one blank line above and below it.

1. All roles must have an associated document under roles-<ROLE_NAME>, where <ROLE_NAME> is the name of the role as it appears in the roles directory.

1. All projects must have an associated document under projects <PROJECT_NAME>, where <PROJECT_NAME> is the name of the project as it appears in the projects directory.