On 12 Oct 2005, at 20:38, David Baird wrote:
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.
I think the structure for the module documentation as enumerated
below is fine. For the "how to glue things together" bit - the
Maypole::Manual namespace, the way that it is structured makes at
present difficult to manage and update, although the guidelines
below are also fine.
I will have some time to have a go at documentation issues very soon
now (end of this month, beginning of next...)
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
-------------------------------------------------------
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
