[Doc-SIG] [Python-Dev] that library reference, again
Ian Bicking
ianb at colorstudy.com
Fri Dec 30 20:48:25 CET 2005
David Goodger wrote:
>>The problem is that the WORKFLOW doesn't work.
>
>
> So fix the workflow. Something like Ian Bicking's Commentary system,
> or something more specific to Python's docs, seems to fit the bill.
I'll just note that Commentary works on any HTML, so it doesn't matter
what the original source is written in.
Obviously it is better if the markup of submitted comments match the
original format; but it's unreasonable to accept LaTeX input in comments
and render that to HTML for inline display. When I have a chance I want
to add ReST input, since some level of markup in comments is really
called for, and I prefer not to create Yet Another Wikiish Markup (and I
like ReST). But manually translating ReST to LaTeX when integrating
comments is no harder than any other manual translation, and people have
indicated they are willing to do that translation.
Because Commentary writes to flat files, workflow should be fairly
simple -- you submit most updates as comments. Maybe a login or CAPTCHA
should be added to avoid spam flooding. rel=nofollow on links is a
no-brainer as well (since unlike a Wiki these are relatively transient
bits of content, so you aren't trapping link information forever by
putting this on all links), but nofollow isn't likely itself to stop spam.
Anyway, submitted comments can be edited by hand through a text editor,
alongside the original documentation, or through the web interface
(right now anyone can delete a comment, but we could restrict that to
documentation maintainers). If the documentation contains good ids
(that can be traced back to the original source) I think it is
reasonable to do the entire process using the text files (comments are
marked by their relation to a nearby id) -- but the current
documentation has rather meaningless ids, so this might not work.
The flat files can also go in Subversion, with useful diffs and complete
history, living safely in the same repository as the documentation or in
a separate repository. Comments can be branched or dumped or whatever,
with a workflow parallel to the documentation. Notification and
tracking tools already exist for Subversion; additional feeds and
whatnot could also certainly be built for Commentary, but it's not clear
that is necessary.
Commentary is still rough in places, but it's pretty much orthogonal to
all the other parts of the documentation system, so it doesn't require
any big investment or conversion process. Heck, it doesn't even require
buy-in by anyone (except, perhaps, at least one person to generate
comments and one person to consume them), though at some point if it
works well it would be useful to link it from the official
documentation. But I think it can be useful in a non-official state as
well.
Right now most people who might be willing to contribute to the Python
documentation don't. Well, "most don't" is an understatement. "Hardly
any" would be more accurate. If just a small portion of people could
contribute fairly easily that would be a big step forward.
Anyway, another even more expedient option would be setting up a
separate bug tracker (something simpler to submit to than SF) and
putting a link on the bottom of every page, maybe like:
http://trac.python.org/trac/newticket?summary=re:+/path/to/doc&component=docs
-- heck, we all know SF bug tracking sucks, this is a good chance to
experiment with a different tracker, and documentation has softer
requirements other parts of Python.
--
Ian Bicking / ianb at colorstudy.com / http://blog.ianbicking.org
More information about the Doc-SIG
mailing list