[pmwiki-users] DocumentationGuidelines updated

[Neil Herber]

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