Ok...this ROCKS! I just make a suggestion, and before I know it, someone else has done the proposal! I couldn't get this kind of response when I had 16 developers who actualy worked for me! This is cool! > Hi cocoon-docs, > <snip/> > > The idea is to split the docs projet into five areas (Concepts, Tutorials, > Reference, > Navigation, Wiki). I know this has been discussed before, but I think the > recent discussions > about manpages and javadoc tags bring new light to this issue, and I don't > think we have a > precise doc plan yet.
Too limited as an actually taxonomy, but might work for a site information architecture. > <snip/> > > Concepts docs > ------------------- > Describe Cocoon at a high level: purpose, architecture, component types, > usage examples, > strengths and weaknesses, similar systems. > > Also point the reader to books and articles. > > Written by doc authors who are not necessarily developers. > Stored separately from the source code (different directories in the current > CVS, maybe > separate CVS later). Ok...fine here. > > Tutorial docs > ---------------- > Tutorials and How-Tos, used by someone who, based on the Concepts, decides to > try or use > Cocoon. > > Written by doc authors who are not necessarily developers, maybe users that > know about some > component without necessarily having the big picture required to write on > Concepts. > > Each tutorial must include links to all components used (allows a map of > docs/component > dependencies to be built?) > > Stored in the same way as Concepts, separately from the code. > agreed. > Reference docs > -------------------- > Detailed information on every component, in unix manpage style: one page for > each component, > always with the same document sections, including a "see also" section. > > Must be written by developers (at least in draft form) when components are > created. Might be > revised by doc authors later on. > > Might be generated from javadoc tags, or using separate XML files stored in > the component's > source code directories [1]. > There are multiple types of refernece docs to be accomodated though. The man pages (need a good name for these, or just agree to adopt the Unix term), JavaDocs, etc. Also keep in mind that if this really follows the Unix model, there may be man pages for things other than components, such as file formats, etc. Possibly a man page with a quick summary of the sitempa syntax and usage - who knows. Point being, it could be a bit broader in application. > Navigation layer > -------------------- > A navigation layer, decoupled from the physical docs structure ,is needed to > make the docs > easy to find and to implement permanent URLs for reference docs (I think > Forrest/Libre will > help here?). > > I'd like the WikiTextGenerator manpage, for example, to be found under > docs/reference/generators/WikiTextGenerator.html, irrelevant of where the > docs come from > (including if they come from a Block later?). > > The top-level navigation uses the same categories: Concepts, Tutorials, > Reference and Wiki. > I agree here...knowing where to find this stuff is important. > Wiki > ----- > The Cocoon DocoWiki acts as a kind of scratchpad for draft documents or for > annotations to > existing docs. > > Note that having permanent URLs for docs might allow using the Wiki for > annotations, by > defining a mapping from docs URLs (as above for > WikiTextGenerator) to Wiki pages that contain notes > .(.wiki.jsp?page=NotesOnReferenceGeneratorsWikiTextGenerator). Links to the > annotations pages > could then be generated in the docs. > I admit that I am really just ignorant of the whole Wiki concept and usage. It is one my list of todos, but haven't had a chance yet. Cool name though.... > Appendix: Documentation Format > ------------------------------------------- > Base format is xdocs, some documents being converted to xdocs from other > formats (howto DTD, > javadoc tags, ?) on the fly using Forrest. > > - o - > > That's only a first shot at this plan, of course ideas/flames/contributions > are welcome. > But much better than I came up with! Again, thanks! > I leave for the Ghent GetTogether in 7 hours (yee-hah!) so I might not > respond to comments > before Wednesday. > > - Bertrand > > > Notes > ------- > [1] > For manpages, I like separate XML files better, using naming conventions, for > example > > src/components/MyComponent-manpage.xml > describes > src/components/MyComponent.java > > When programming, I wouldn't want my NiceAndSimpleComponent.java file to > contain too many > javadoc tags and documentation text. Also, Blocks might not be shipped with > source code, in > which case it will be easier to include a Block's manpage in XML form with > the block. And > finally, having "magic" filenames for such docs makes it easier to generate > them. I completely agree here! put it in the same place, use a naming convention to correlate the files, but don't put it in the code. And an XML format is best... -- "The heights of genius are only measurable by the depths of stupidity."
