Hi Jay,
as I said on another reply, don't worry about the wiki format, doc structure or
refined content, I'll take that bullet.
We need to focus on what to cover and how. When we have the content, it is easier to move it around within the wiki, edit it and to give it a consistent look with the rest of the docs.
If you want to look into the formatting we've been using in the past, I created
this page long time ago to help me (and everybody adding content) be consistent
with the existing doc.
http://cwiki.apache.org/geronimo/tips-for-writing-and-formatting-documentation.html
I'm about to shoot a separate thread for discussing the content, pls chime in
with your ideas, I'll put there mine as well ;-)
Cheers!
Hernan
Jay D. McHugh wrote:
Kevan Miller wrote:
On Jan 25, 2008, at 11:22 AM, Hernan Cunico wrote:
Guys, I've been trying to get your attention around Geronimo 2.1
documentation since October last year.
Apache Geronimo is as good as you can communicate it to the users.
How do you expect the users to know all the beeps and whistles? Not a
best way to tell the users HOW TO do things in Geronimo than by
having a good documentation.
How much of your time it would actually take to write up a page
describing a component or module and how to use it? It's you writing
the code, why not you writing about that code and how to use it!?
There are tons of questions on the user@ and dev@ lists about how to
perform basic (and some times not so basic) tasks and configurations,
we get these all the time. This is a clear sign that we need to
improve the way we document the things.
For 2.1 the situation is even worse, we pretty much don't have any
documentation and we can't continue developing documentation the way
we've been doing in the past. The way it looks now, Geronimo 2.1
won't have supporting documentation.
Let's discuss here what areas need to be covered and who can work on
documenting them. It is your turn now.
Hernan,
I hear your pain. And totally agree that good docs will make things
much easier for our users (as well as ourselves).
I know I'm as guilty (perhaps more so) as anyone else at failing to
help pitch in. Everybody's pretty busy. Also, there's a definite
tendency for skilled developers to be, well, skilled *developers*.
Perhaps there are some alternate ways to help this process go faster?
I wonder if it would be easier for people to discuss a particular
topic with you on a phone call? Hopefully providing enough information
for you to transform into flowery prose and lucid illustrations? If we
want, we could make this a conference call (so interested parties
could join).
I don't think this technique can work for all docs. We can't expect
you to write everything. However, it might help kickstart the process
in some critical sections...
--kevan
If folks think that something like this could work - I would be happy to
chip in as a typist. I took a look at the shell for the documentation
and realized that I know far too little to be able to write the docs
from scratch.
Plus, it would be useful for me to be able to get more familiar with
everything.
Jay
