[Doc-SIG] [Python-Dev] that library reference, again

[Ian Bicking]

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