A long time ago I did some updates on the manual. I wrote some
guidelines to help myself then, so here they are in case they're of any
use to the group now:
A/ The manual should be explanatory and guiding. It should:
1/ Cross-reference the modules where appropriate,
2/ Provide beginner's how-tos,
3/ Provide more complex examples,
4/ Describe cross-module interactions (e.g. initialization and request
workflow),
5/ Describe extension mechanisms.
It should not provide a detailed reference; that should be in the modules.
B/ Documentation in modules should:
1/ have a short para summarising the purpose and functionality of the
module, even if it's only a technical module like *::Base
2/ have a section for *every* method or other externally-facing facility
that contains:
2a/ an example of all uses, and
2/b a description of all parameters
3/ cross-reference all inherited and used modules
4/ cross-reference the relevant manual section(s)
on the other hand there should be:
5/ no tutorial,
6/ no complex examples
because these should be in the manual.
I think the general plan of the manual is not too bad, but I also had a
list of extra sections I'd like to see (apart from the obvious
incomplete sections in the manual). Some may be familiar:
- configuration
- debugging
- access control
- initialization sequence
- inheritance graph
- extension mechanisms
I have some fragments of some of these.
Cheers, Dave
-------------------------------------------------------
This SF.Net email is sponsored by:
Power Architecture Resource Center: Free content, downloads, discussions,
and more. http://solutions.newsforge.com/ibmarch.tmpl
_______________________________________________
Maypole-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/maypole-devel
