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.
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.
Entries Should be sitefaqlets
(OBE) The 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.
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.
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 :
A faqlet's title should be at the top of the document in h1 tags.
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.
