[haiku-doc] Re: I'd like to volunteer, as well

Hi Bruno, Niklas and Richard,

Thanks for your interest. I'm writing this message from Valencia,
where I'm staying a few days, that's why I did not respond
immediately. I'll try to briefly put up some ideas in this message,
and then on monday when I return to Bilbao, we can structurally
discuss some of the points.

First of all, it might be a good idea to have a list of things that
are already there. I urge you to check out the API documentation
guidelines 
(http://factory.haiku-os.org/documentation/Haiku_Book_doxygen/html/apidoc.html).
These guidelines are by no means final, and I expect us that we find
some of the ideas inefficient or invalid, but I guess they're a good
starting point. So please have a good read through them, and in case
of questions or notes, feel free to post them on this mailing list for
discussion (though I urge you not to get too picky on issues that only
exist in theory). I don't think it's necessary to actually have a look
at the doxygen documentation, I guess a look at the guidelines and the
existing documentation should be enough.

Secondly, you'll need an svn checkout of at least the headers and the
docs subdirectory. If you need any help I can find out the commands
for you, but perhaps someone else can step in (because if I do it, it
will have to wait until monday). You will not have to checkout the
whole tree, which is good, because that thing is huge.

Thirdly, you also need the doxygen binary. I hope most of you are able
to compile. If not, I hope that someone can provide us with a binary.
I  cannot, since I'm currently forced to work on a Windows computer.
Any volunteers? As soon as you have the source and doxygen, it is
fairly simple to start compiling the documentation yourself. Just do a
'doxygen' in the /trunk/docs/user subdirectory. The generated
documentation will be put in the '/trunk/generated/' directory.
Currently, doxygen spews out a load of warnings because of the
filesystem API and the USB documentation (the last one is my bad).
We'll need to clean this up. Nevertheless, the documentation will be
generated.

As soon as you have done these steps, you are able to happily write
and maintain documentation. So what's next?

With Alan and Miguel we started to discuss how to proceed. Currently,
what's documented is the support kit, which is sort of inconsistent
because it's the product of my experimentation with doxygen. Also the
midi2 kit, documented by Matthijs Hollemans, is in the repository, but
it was done long before my attempts, and it is somewhat inconsistent,
and in areas, informal. Ingo Weinhold started on the filesystem API,
which is rather technical and uncharted territory for many, and I
started on how to write USB drivers.

At the moment we are with six volunteers (including me), of which one
definately wants to proofread. These are the tasks (in order of
priority):
- Finish the support kit documentation. Make sure the docs adhere to
the API guidelines, or the API guidelines adhere to the practical
problems.
- Have a good look at the midi2 kit, and rewrite it partially. It
needs many updates with regards to references to other locations, and
it needs to be restructured according to our guidelines.
- The instructions in this e-mail need to be transferred to a webpage
or a wiki page or whatever is appropriate, so that other interested
people can join in easily.
- And (probably of least importance) one of the other kits should be
started. I have some ideas on how to do this, but I will probably digg
up an older email monday to prevent me from retyping the whole stuff.

I say we work in a teams of two to do the first task, and one on the
second and third task. Niklas, Alan, (did I forget a native speaker?),
you can proofread afterwards. The fourth task is for later, unless
someone has a very innate desire to start it now. I'll continue on the
USB documentation and on the filesystem API, since I already worked on
the support and midi kits and I think they need a fresh eye. I'll say
it's best to work according to the 'first come, first go' principle,
in order to avoid everybody saying 'I don't mind what I do'. So
people, go call dipps (or whatever the expression is). I'll try to
check back again tomorrow, and else I'll speak to you all on monday!

Let's get started.

Niels

Other related posts: