Public SourceMage Discussion List

[Donald Johnson <ltdonny AT gmail.com>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hey, Source Mage Valley.  Donald here.

My opinion on the docs is that they could use a nice cleanup.  So, I
have made some document guidelines, which kind of turned out RFC-style.
But, I can't help it.

The Documentation Guidelines are attached and also available at
<http://sourcemage.org/Tome/DocumentationGuidelines>.

Anyway, what I am requesting is that people review documentation with
these guidelines in mind and chat up some lines in #sourcemage-tome.
Comments on any range of the documentation covered or (not covered) are
welcome.

I would place priority on the local man-page documentation, especially
removing first or second person in a few of the man-pages to present a
more technical style.  The wiki is much easier to edit, but hit up Tome
before or after you commit an edit please! ;)

My goal for now is to get the documentation straightened up.  As a rule
of the thumb, if you are forced to resort to previous examples instead
of the docs to remember something, you should hit up Tome and complain.
If it is confusing, hit up Tome and complain.  Right now, I would place
a higher priority on filling the lack of documentation and removing
obsolete documentation first than going onto the more tedious stuff such
as rewording entire sections to remove one instance of "you".

Also, the wiki command docs could use some standardization.  I'm leaning
towards standardizing towards Cleanse as an example on this one.

However, these are almost entirely my ideas on how things should be
documented and they may have shortcomings.  So, I wish to get feedback
from all of the Valley.

~Donald 'minozake' Johnson
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.10 (GNU/Linux)
Comment: Sender=Donald Johnson

iEYEARECAAYFAkrNDQgACgkQ/YxjcymZYJisXACgmebR/YzXZErxDbKa0VD8Df68
7i4AoLDJVRVa9VknHCEslX6VQjv3h6jC
=5171
-----END PGP SIGNATURE-----
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 types of documentation.

This document was created by the Source Mage Tome Team and modified on
2009-10-07 as revision 02.

2. General Guidelines

All text SHOULD be wrapped to a standard 80 lines or less in both cases
when possible.  The MoinMoin wiki markup is 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 have no first or
second person text.  This will ensure a generally more technical 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).  Man-pages are
RECOMMENDED to be released with new updates of commands, and updates to
the code that would result in incorrect documentation MUST to 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 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 have first person in questions it contains and MAY have
   second person in the answer to the questions.  Reviewers SHOULD NOT
   attempt to remove these if present.  All FAQs with more than three
   questions SHOULD have a table of contents.

   4c. HowTos

   HowTos MAY have a second person point of view in the documentation as
   reasonable.  HowTos SHOULD have a step-by-step process when feasible.
   Newly-created HowTos MAY have first person view where additional
   content can go for further update, but SHOULD use comment markup for
   this purpose instead.  HowTos older than three months old SHOULD have
   no first person point of view present.

   4d. Miscellaneous

   All mentioned guidelines for other pages on the wiki are OPTIONAL.



A. Footnotes

[1] - Hanging indents are indents that proceed the first line of text
      where defined (e.g. this footnote).

Attachment: document_guidelines.sig
Description: Binary data