[lxml-dev] help needed for cleaning up the docs

[Stefan Behnel]

Hi,

since Marcin brought this up, I'd like to aggregate some effort for cleaning
up the docs in the "doc" directory (ReStructured Text format).

http://codespeak.net/svn/lxml/trunk/doc/

For example, I find the current homepage (main.txt) lengthy, unfocused and
overwhelming. It only remains usable due to the menu on the left, not by its
content itself. There should be a better balance between the amount of content
and its accessibility. Maybe the "Changes" section and a part of the
"Download" section could go on the installation page, for example.

I also find the "Documentation" section too detailed. The list may be fine,
but the explanations could be moved to the FAQ entry on documentation, or
maybe even a dedicated documentation page.

There's also the "APIs specific to lxml.etree" page (api.txt), which continues
to be a mess of things that belong nowhere else. It's outdated, badly
integrated into the rest of the documentation and overlaps with other docs.
The tutorial, for example, has a more extensive section on iteration, and
things like the error log should also be handled in the tutorial. Maybe the
current api.txt is the right place to start a general "start here" page on
documentation?

I'm unsure what to do with the "why lxml?" page (intro.txt). I think the
content should be there, although it's somewhat dated by now. But I don't feel
like it merits its own page (or chapter in the PDF). Maybe a FAQ section would
do, although that would be a much less prominent place (and it's not really a
FAQ anyway...).

Same for the "what's new in 2.0" page (lxml2.txt). Since lxml 2.1 is close, it
will soon loose it's front-page topicality.

I would be very happy if a couple of people could spare hands and thoughts on
this topic. I find accessible documentation very important, and it's something
everyone can work on who wants to give something back to the project.


Thanks for any help!

Stefan