Re: [Paparazzi-devel] We Need A Good Manual

[Tilman Baumann]

Arun Sajeevan wrote:

> Can some body tell me where I can get some good tutorials for learning the
> basics of OCAML?

This is actually a very good point. Well, not quite the one I'm trying to
make but it reminded me.

When I was trying to understand paparazzis architecture by reading code, I
had most of the time no idea what what code is good for.
Most of it is very flat directory structures and totally uncommented about
its purpose and only strung together by sample xml files. (I could only
assume that those xml files will make sense of it, I gave up finding the
ties)

I for example found it very hard to understand what code is module
specific, which code is actually used and which is test code.
Readme files in directories and short code comments in the file headers
would help a long way.
I know those things are very hard to do and keep up to date. But it would
make the code way more accessible to the general public.

No, I'm not asking for somebody to go through the code and do this. But
please keep this in mind whenever you do stuff in the code, and soon it
will make much more sense.
Reading code is obviously the best documentation, but only if you are
interested in a deep insight. It helps little for a broad overview.

Thank you
 Tilman