commons-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Martin Kersten" <Martin.Kers...@Student.Uni-Magdeburg.DE>
Subject Re: [Digester 1.5] Pattern matching screwed me up
Date Sun, 29 Feb 2004 11:23:13 GMT
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: commons-user-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-user-help@jakarta.apache.org


Mime
View raw message