[pmwiki-users] DocumentationGuidelines updated
Neil Herber
nospam at eton.ca
Fri Aug 12 16:35:40 CDT 2005
At 2005-08-13 12:51 AM +0530, V.Krishn is rumored to have said:
>So I guess we would use this document as an example template while editing
>other documents.?
If by template you mean that other docs should follow this structure, I'm
not sure if I would go quite that far. The guidelines should be ... well
... guidelines!
Certainly the guidelines need to be self-consistent. So if they say keep
things simple, they should be simple. If they say use headings to chunk the
information, they should do that too.
However, this is a relatively special purpose document, so I am not sure
that the structure would suit other pages. That said, the guidelines
provide a stark example of "newspaper-style" writing, where you tell the
whole story right at the start and then elaborate on the details later.
This allows readers to get a quick appreciation of the subject at hand -
and for many, that will be enough. Anyone looking for a little more
discussion or examples can read further to find them.
Maybe that principle is worth adding as a guideline! ;-)
Neil
Neil Herber
Corporate info at http://www.eton.ca/
Eton Systems, 15 Pinepoint Drive, Nepean, ON, Canada K2H 6B1
Tel: (613) 829-4668
More information about the pmwiki-users
mailing list