Documentation Plans¶

Task documentation has historically not been very good. This is changing. What do we want?

I'm not happy with the state of the online docs for task. I only have myself to blame, but they could be a lot better. It's been a largely haphazard incremental effort, and if all the pages were printed and put together, it would make the most dreadfully organized, short, incomplete, chaotic book. It is currently about 5,000 lines of HTML.

If we were to start again with the online docs, what form should they take?
- HTML?
- PDF?
- Is the movie of any value? (we have a filmmaker in our midst)
- Do we need more man pages?
- Does anyone know how to properly structure a set of docs? I clearly don't.

Our new man pages are a big step in the right direction. But I feel there needs to also be a more in-depth set of docs.

Thoughts please.

(ultrafredde) I have a couple of thoughts and ideas. Though I might not be able to write them down into this page right now. Perhaps in a couple of hours later during the evening. Just to mention a few things: automate the generation for parts of the documentation and website, tutorial (perhaps interactive???), all documentation as html and man pages, pdf - why not at least for the tutorial, movie - certainly, it make it so much easier for "newcomers" that are interested to get a picture of what task can do and how it works. If it's OK with Paul I'm willing to volunteer in organizing the documentation part of task - so that he gets more time for coding :-)

pb: Fredde, are you saying I don't do enough coding? Just kidding.

pb: I approve - Fredde please figure out what the task docs ought to be. Specifically, the man pages, tutorial and online doc equivalents - not djp's sandbox, he's busy in there. As for the movie, I had a lot of fun making that, and I know Sarah enjoyed narrating it, so I volunteer to do more, if you tell me what we need.