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

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
participants (1)
-
Stefan Behnel