Hi Simon, [...]
> > Here is what I would like to do: > > > > 1. Write a getting-started.html put into the docs directory telling people > > where > > to look for the 'orginal' documentation (link to the package description). > > 2. Write a tutorial teaching the pattern matching and xml-parts mapping. [...] > > I guess it would take me additional 4 hours. But I would likely to > > contribute that > > peaces. But again, I need a person who's playing the English teacher. [...] > > Thanks for the help, it seams to work now and I am going to alter my test > > cases > > to avoid top-level attributes containing itself and adding an interface for > > adding > > (cause this function is called within two tags). > > I'm glad your code is now working. Me too. The documentation just needs some adds to avoid this. > > And I think it's great that you are really willing to help with > documentation. I didn't mean to imply that Digester's documentation was > perfect - we all know it's not. But there's a line between helpfully > pointing out an issue and complaining/criticising. Of course those who > are willing to actually *do* something get forgiven a lot :-) Well I just said that the documentation is bad :) Which is a statement, I would still sign. Maybe I shouldn't had said bad, just incomplete and for a 'jakarta-doing-everything-within-packages.hml' newbie it was hard to find it. 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... I would like to see a note about the composing of the documentation. Like the documentation is part of the api documentation (link to it). That would have saved me one hour :). I am really not used to this kind of documentation style. > > First thing to check is whether .html form is the correct format for new > docs. I know that at least some docs at Apache are in something called > "xdoc". I'm not sure exactly what xdoc is, though. > > Then there's the issues of deciding where to put the docs, and how to > link to them from the project site. That probably involves some Maven > configuration. If you can find a commons project which has documentation > along the lines you are suggesting, and can investigate how they write & > deploy it, that would be good too. Oh gosh I would like to add content but not to learn Maven, xdoc and stuff. That would really be a pain :( Is someone else able to do contribute documentations? > > If you can do that, and produce some intros/tutorials, I would be > willing to do some proof-reading if you wish. Thanks! > I'm currently (and concurrently) learning Websphere, Debian, Linux > network security, nagios, LVM, LDAP and subversion, so my poor brain > isn't up to learning xdoc or Maven at the moment. Same here. I am doing Eclipse plugin programming for my final exams work and would also avoid learning xdoc and maven. There should be some people available being able to contribute a tutorial and correct the documentation notation;) > > I think a few people are in this same situation, which is why writing a > package.html file (which is standard html/javadoc) is so much easier > than writing external documentation like you are proposing. Why they don't change the way you must work to contribute documentation? > > You'll find quite a lot of documentation written as package javadoc, so > it's a good habit to check for it when learning a new library. Yeah thats the lesson I've learned. But a (more prominent) note on the main page would have saved me from learning it the hard way. > > Oh - and if you want to see a really badly documented library, I suggest > looking at IBM WebsphereMQ Cluster Workload Exits. And they get *paid* > to write that stuff :-( Don't tell me about bad documentations! :-) I had to analyse lots of source code for my final exam. There wasn't even much java doc available. And the man who wrote the source seams to be hugged to the 'as long the method as good it is' style. There where classes spanning over 1000 lines. But the code is also three years old. Thanks, Martin (Kersten) --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
