Site Documentation Plan

1. Ailie's Master List

   I have taken as the basis of future documentation work, ailie's outline of documentation. Her outline is arranged in a coherent and logical manner that's much clearer than the array of nodes and faqs that's currently in place. While it is comprehensive, there's always room for improvement and changes in documentation. All discussion on the subject should take place in the wiki.

2. Site documentation should be functional in nature.

   In particular, this means that documentation should have as little editorializing as possible. SDC members are writing for Perlmonks, and the FAQs written will rapidly become policy, so as little of the opinion of the author should show in a document. This is not to say that FAQs should be clinical, or void of humor. There are some topics (voting, in particular) that invite opinions, and when these subjects are written about, it should be the opinon of Perlmonks that is voiced, first as determined by the gods -- they are the maintainers and policy-makers of the site -- then by the general consenus of the Perlmonks userbase.

3. Entries Should be sitefaqlets

   The Old Perl Monks FAQ is, naturally, where all documentation work should link from. This node contains a link that allows SDC members to create new FAQ entries.

4. Entries Should make heavy use of perlmonk links, existing community opinion.

   Whenever possible, make use of Perlmonks to document Perlmonks. Links to site discussion nodes, pointers, &c. will lend strength to the information presented in a faqlet.

5. Edits should be documented.

   Whenever a faqlet is edited, a brief comment at the top of the code should be added, which takes the format :

    
         <!-- YYYY-MM-DD [Username] brief edit description -->
   [download]

6. Entries should be titled

   A faqlet's title should be at the top of the document in h1 tags.

7. Entries should make use of anchors when appropriate

   If a faqlet has several subpoints, they should be titled in h3 tags and linked appropriately at the beginning of the document in an outline. If a subpoint warrants its own subpoints, they should be titled in h2 tags, and linked appropriately in the outline and at the beginning of the parent subpoint (example.

8. Communicate

9. Site FAQ page needs to be updated.

   The Old Perl Monks FAQ needs to be reformatted. Suggestions welcome.