FAQ for documentation team members
How do I get started?
- As a start, everybody should have a Python checkout and a doctools checkout. The SVN URLs are
http://svn.python.org/projects/python/trunk and http://svn.python.org/projects/doctools/trunk
(There are some tips on SVN at http://www.python.org/dev/faq/)
The doctools directory contains all the toolset that's been written so far (moved there from the docutils berlios SVN).
The README file in there tells you how to get started with the conversion and how to use the "sphinx" [2]_ builder. (At least on *NIX, if anybody wants to work out a similar thing for Windows, feel free
The Python directory contains the source code of Python and has a subdirectory called Doc/, in which the current LaTeX sources lie, and which we will replace sooner or later with the reST sources.
What time commitment is necessary?
- As this is a voluntary effort, nobody is "required" to do anything. When the new system goes live, it depends on the amount of comments and change suggestions that come in how much the group will have to shoulder. (More on that below.) But as always, every contribution helps.
What mailing lists are there?
The docs@python.org list will mainly be our private coordination place. (The archives are not publicly accessible.) Additionally, outside mails to docs@python.org will get here too, they can usually be answered, and if needed, discussed, quickly. Also, for a start I had in mind to let the web application send patches and comment notifications here too, which can later be changed if the traffic gets too hard.
There is also the Doc-SIG (special interest group) at doc-sig@python.org, which is at the moment quite deserted. In the tradition of open source, I think it would be good if discussions that are of public interest are at least crossposted there, in order to allow others to participate.
What other infrastructure is there?
- While a mailing list is a very nice thing to have, sometimes a Wiki page is better suited to coordinating a task. For now, we have the subhierarchy of the Python wiki here -- if this is found impractical, we'll have to think about some other solution. As a bug tracker, we'll use SF for now, and the new bugs.python.org tracker as soon as it goes live. I'll have a new category "doctools" created in the latter, so that content and toolset bugs can be separated. Finally, I've set up an IRC channel #python-docs at irc.freenode.net. I'll be there most of the time, so short questions can be settled there as well with private email; everyone is welcome to join and idle there.
How do I get SVN commit access?
Those of you who'll contribute more than the occasional patch (which can be just mailed to a committer) can get SVN access to svn.python.org. For that, I'll need an SSH2 compatible public key, your full name and, of course, your word that you won't touch things outside the documentation tree
