Documentation Guidelines
Table of Contents:
1. Intro
2. General Guidelines
3. Man-page Documentation
4. Wiki Documentation
4a. Command Pages
4b. FAQs
4c. HowTos
4d. Miscellaneous
A. Footnotes
1. Intro
Key words in this document will be based on RFC 2119. Review RFC 2119
at <http://www.faqs.org/rfcs/rfc2119.html>.
These document review guidelines have been written as a result of
sub-par documentation being present on both the Source Mage Wiki and in
the local Source Mage docs. The scope of these document guidelines
should cover both the man-page documentation and the wiki documentation.
This document was created by the Source Mage Tome Team and modified on
2009-10-15 as revision 04.
2. General Guidelines
All text SHOULD be wrapped to a standard 80 characters per line or less
in both cases when possible. The wiki markup may be buggy at times and
may not allow a wrapped line to exist without glitches. This should not
be a problem for man-page markup.
Markup glitches MUST be noted by comments within any document. This is
to prevent making the same markup glitches twice when two reviewers
revise the document.
All documentation excluding HowTos and FAQs SHOULD NOT have any first or
second person text. This will ensure a generally more uniform writing
style and the communication of ideas more clearly.
3. Man-page Documentation
Some of the man-page documentation is outdated and disorganized.
Man-pages MUST follow the guidelines set in man(7) and its references.
The guidelines in man(7) and its references supersede these
documentation guidelines. Man-pages are RECOMMENDED to be released with
new updates of commands, and updates to the code that would result in
incorrect documentation MUST be communicated through the bugtracker or
through the official Tome IRC channel. Man-pages SHOULD have
alphabetically-organized lists. If argument order is important,
man-pages MUST list those before the rest of the list items, possibly
breaking alphabetical ordering. If arguments to a command are
subcommands, those arguments SHOULD have hanging indents[1] to their own
arguments.
4. Wiki Documentation
Wiki documentation includes the command pages, HowTos, and FAQs.
4a. Command Pages
Command pages for the Sorcery scripts SHOULD describe the same
functions as the man-pages, but MAY have a different wording in order
to possibly clarify further for end-users. All multi-line commands
MUST be in code blocks. Single-line commands SHOULD be denoted
within a paragraph in monospace, but MAY be denoted in code blocks.
4b. FAQs
FAQs MAY use first person in questions they contain and MAY use
second person in the answers to those questions. Reviewers SHOULD
NOT attempt to remove these instances of first/second person if
present. All FAQs with more than three questions SHOULD have a table
of contents.
4c. HowTos
HowTos MAY use second person in the documentation as is reasonable.
HowTos SHOULD follow a step-by-step process when feasible.
Newly-created HowTos MAY use first person where additional content
can go for further update, but SHOULD use comment markup for this
purpose instead. HowTos older than three months SHOULD NOT have any
use of first person.
4d. Miscellaneous
The above mentioned guidelines are OPTIONAL for other pages on this
wiki.
A. Footnotes
[1] - Hanging indents are indents that proceed the first line of text
where defined (e.g. this footnote).
Tome/DocumentationGuidelines (last edited 2009-10-15 21:47:37 by DonaldJohnson)