> > After going through it again, the JavaDoc API documents are > > available online statement, mention to read the package description. Maybe > > this should be said top level. The documentation is hidden within the API > > documentation. You know I just glaced over it and saw the api > > documentation is online. The second line didn't seam to be important at > > first... > > > > In the home page for Digester: > > http://jakarta.apache.org/commons/digester/ > > the second section of the overview is entitled "Documentation". And the second > paragraph there states: > > The JavaDoc API Documents are available online. In particular, > you should read the package description for the > org.apache.commons.digester package for detailed information > on using the package. > > I'm not sure how we can say it any more "top level" than that, but would > certainly be interested in any ideas there. (A similar comment is made on the > first page of the JavaDocs themselves.) The problem is, that I wasn't that used to common libraries before I got interessted in digester. I am also only using JavaDoc as part of the source and not as a part of the user guide. I was never used to see JavaDoc as a user guide but after I 've read all tutorials twice I remembered the JavaDocs and looked for 'em since I was debugging digester and wanted to understand how everything works. Thats when I found the 'documentation'.
How about changing: [snip] The Release Notes document the new features and bug fixes that have been included in this release. The JavaDoc API documents are available online. In particular, you should read the package description for the org.apache.commons.digester package for detailed information on using the package. [snap] to: The Release Notes document the new features and bug fixes that have been included in this release. The Documentation is part of the JavaDoc API documentation. In particular, you should read the package description for the org.apache.commons.digester package for detailed information on using the package. The JavaDoc API documents are also available online. I think this would be more intuitve to the user. I am trained to read fast. Therefore I apply to some fast reading technics. I'll show you what happens when I read the documentation: First paragraph: ... Release NOTES DOCUMENT ... blah blah. (found document but interessted) ... javadoc API DOCUMENT are available ONLINE. In particular, you should read the PackagE description for the org.apache.commons.DigesteR PackagE for detailed information on UsinG the PackagE. Thats how I see this. I was looking for something that helps me. Therefore I use to read for document. The words starting and ending with a upper letter are also interessted. If a interessting word is recognized I start thinking what the sentence is meaning (everything is automated but thats how it works). And you see the second part is quiently marked as not important because I did not expected some usefull informations. But the refactored part above have everything what is needed to get me attracted to the required informations. So I would like to see it changed. I am not the only one reading that way :-). > On the general topic of including user guide documentation in the JavaDocs, > you'll find this to be quite common in the various Commons packages. The > reasoning is that these packages are, after all, class libraries to be used by > developers, and those developers are going to need the JavaDocs in order to > understand the valid method signatures and so on, no matter what. I am using Eclipse. I am trained to see class documentations as tooltips so I've looked for the java doc of the methods and not of the entire package. I didn't found qlues about the pattern usage. > I've seen cases where class libraries were documented separately, and the user > guide was never read because developers tended to think a "user guide" is for > the user of their own application, not for the library they are trying to use, > and wouldn't read it. This way, all the information that a developer needs is > accessible in one place. That spare documentation and developing documentation seperately is an issus I understand. To be honest we are doing it the same way here. JavaDoc is used to support developers. After the iteration comes to an end, the JavaDoc is reworked (cleaned up mostly through method splits and extractions) and after being reworked, the public methods of public classes are described in more detail. But after every iteration a user guide is also updated. > > A separate benefit is that the user guide can contain direct links to the > detailed JavaDocs for the classes it talks about, because the directory > structure for where package.html files go is well defined. > Trying to do this with separated user guides leads to much more fragile > links, in my experience. > > Thanks for your offer to help! No problem. I would suggest the following to prevent another one falling some traps I went through and wasted 4 hours of my life. Well not wasted entirely but it wasn't that productive also. a) refactor the The JavaDoc API documentation is available... and split it up and mention the documentation being part of the api in first place. b) alter the package documentation to reflect whats happening when it comes to self containment. (tag contains itself as child, the information was lagging). I think this would had suited me and doesn't break any of your documentation requiries. Thanks for providing digester! Saved me some hours of work and is a great thing to have in your toolkit! Thanks, Martin (Kersten) --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
