I meant to say I think these guidelines are excellent. The one addition I'd make is thatthere should be a documentation roadmap in Maypole.pm. I'm trying to find some time to get stuck in to this.
Kieren, I think the current structure is fine, the main problem is finding time to do this, rather than rearranging the bits. d. On 10/5/05, Dave Howorth <[EMAIL PROTECTED]> wrote: > 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 > ------------------------------------------------------- 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
