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

[Stephen J. Turnbull]

>>>>> "Ian" == Ian Bicking <ianb at colorstudy.com> writes:

    Ian> Nick Coghlan wrote:

    >> While I quite like this idea, would it make it more difficult
    >> when the bug tracking for the main source code is eventually
    >> migrated off SF? And what would happen to existing
    >> documentation bug reports/patches on the SF trackers?

    Ian> I think the requirements for documentation are a bit lighter,
    Ian> so it's not as big a deal.  E.g., the history of bug reports
    Ian> on documentation isn't as important, either the ones from SF,
    Ian> or if all of Python moves to a new system then the history of
    Ian> the transitional system.

This is almost true, but

    Ian> Documentation is mostly self-describing.

is not.  Python maintains several "supported" releases
simultaneously.  There are important differences between the Python
language and the implementation being discussed on this list
(cPython).  These issues (and their historical tracking) are not
particularly important in the current workflow because most of the
people actually touching the docs are highly experienced experts.
They will get this stuff right more or less naturally, in part because
they're working on documents that are directly associated with a
particular version of a particular implementation.

But as the documentation process moves to a more fluid, user-driven
process, that expertise will be diluted (even with proposals that the
last phase be edited by a dedicated expert, that expert's time
commitment will surely be strained).  That means that history tracking
will become more important, and documentation meta-data (like which
version of which implementation does this change apply to) much more
so.


-- 
School of Systems and Information Engineering http://turnbull.sk.tsukuba.ac.jp
University of Tsukuba                    Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
               Ask not how you can "do" free software business;
              ask what your business can "do for" free software.