Differences between revisions 4 and 5
Revision 4 as of 2007-08-02 15:29:23
Size: 3634
Editor: dslb-084-057-013-130
Comment: update
Revision 5 as of 2007-08-03 11:52:25
Size: 3774
Editor: dslb-084-057-057-206
Comment:
Deletions are marked like this. Additions are marked like this.
Line 74: Line 74:
  If you tackle a SF bug, mention the issue number in the commit message or in the patch email, and I will close the report accordingly.

Tasks

for the documentation team

Coding tasks

for those who want to develop the toolset

Get into the code

  • The first task for those who want to develop the toolset is to make themselves familiar with it. There are two documents, called doctools/README and doctools/HACKING, which give a short introduction how to use the command line tools and how the code is laid out. Feel free to amend!

Improvement suggestions

  • I'd like to ask all of you to look at the new built documentation and collect thoughts about it -- not the content, but mainly the infrastructure such as navigational elements, accessibility etc.

    Note that the web application does use JavaScript in some places, but only for better usability (hopefully). Users without JavaScript may not lose any functionality. (This should be confirmed every now and then.)

The TODO file

The doctools/TODO file lists some things that should be done. At the moment, these are:

discuss and debug comments system

  • The comments system is quite new and untested. How it deals with inline comments is not ideal.

write new Makefile, handle automatic checkout

  • We need a Makefile so that one just does

cd Doc
make html
  • to extract version info from the sources and build the documentation.

write a "printable" (PDF) builder (export to latex, most probably)

  • Of course, printable output was trivial for LaTeX sources. The Docutils do have a latex writer (two in fact) -- if it is stable enough to be used, it has to be extended to support our extra node types. Else, some other conversion must be devised.

prepare for databases other than sqlite for comments

  • Does sqlite scale well enough for our comments? Though I think so, we should be prepared to make it easy to substitute something like postgres.

look at the old tools/ scripts, what functionality should be rewritten

  • There were quite a few tools in Doc/tools/, e.g. looking which modules were documented. Some of this functionality is obsolete now, some of it may be useful.

Py-in-the-sky ideas

  • add search via Xapian? optionally have a contents tree view in the sidebar (AJAX based)?

Converted Trees

Now that we have converted trees in doctools/Doc-26 and doctools/Doc-3k, they must be cleaned up and completed before they can replace the LaTeX trees in the Python tree.

All these tasks are listed in the doctools/Doc-26/TODO file, which is copied to the reST source tree on conversion.

All other tasks that are independent of the converter are collected in doctools/TODO.

Content tasks

Of course, before the conversion changes to existing documents have to be made in LaTeX to the original sources. However, you can already start extending and editing the "new" sources in converter/newfiles which don't have a LaTeX counterpart.

SF bugs

  • There are lots of SF bugs and feature requests, and even the occasional patch with category "Documentation". However, most of these are pretty big tasks though, such as (mostly obscure or advanced) features that are not documented, or documented not in the official docs, but some essay (new-style classes!).

    The bug tracker is at http://sourceforge.net/tracker/?group_id=5470&atid=105470, the RFE and patches trackers can be reached through the "Tracker" menu at the page top. If you tackle a SF bug, mention the issue number in the commit message or in the patch email, and I will close the report accordingly.

In the Wiki

DocsCoordination/Tasks (last edited 2008-11-15 14:00:27 by localhost)

Unable to edit the page? See the FrontPage for instructions.