Future of the Packaging Guide

[Emmet Hikory]

On 9/19/07, Daniel Holbach wrote:
> Jordan Mantha started the discussion about moving the Packaging Guide
> from DocBook in the Doc Team SVN to the Ubuntu wiki:
> https://lists.ubuntu.com/archives/ubuntu-motu/2007-September/002290.html
>
> In order to get more opinions and input on this, we decided to move the
> discussion over here.
>
> I try to sum up the pros and cons of the discussion here:

    The listed benefits are a very strong argument for such a
transition, and I'd like to propose the following as suggestions to
reduce the impact of the detriments:

> === Cons ===
>       * probably no nice printable version
>       * what happens to the packaging-guide package?

    These issues seem very related to me: specifically that they
represent mechanisms to make the reference available off-line, to
support those who wish to learn more about packaging with limited
network (or possibly computer) access.  The availability of a printed
edition is further assistive to those who have small available screen
resolution, yet feel more comfortable with a reference.

    From what I can tell from http://moinmoin.wikiwikiweb.de/DocBook,
it appears that neither the current MoinMoin, nor the version used on
wiki.ubuntu.com supports a direct transition back to DocBook.  Perhaps
a spec could be registered to merge the code into Moin 1.6, and
upgrade wiki.ubuntu.com such that this does not remain a long-term
issue.

>       * malicious editing, harder to have QA for it

    This seems most easily addressed by the wiki subscription
mechanism.  If a few interested developers subscribed the the
development guide namespace in the wiki, any malicious changes should
be caught fairly quickly.  By encouraging new contributors to
subscribe "to keep track of the latest best practices", such
subscription QA should survive developer turnover.

>       * work to get the DocBook -> Moin transition right

    Some of this may be addressed by the abovementioned Moin<->DocBook
integration, but as much value may be gained by review of the
materials during the transition, and semi-manual activities, while
time consuming, should ultimately provide a better final solution.

>       * licensing

    This is frustrating, but given that the list of contributors is
well documented, it should be possible to identify any material not
suitable for direct migration, given direct oversight.

<...>

> There were other proposals during the discussion:
>       * moving the packaging-guide from svn to bzr

    A change in the repository, while possibly nice for integration in
other processes, is not very significant in terms of ensuring timely
update of best practices nor ease of publication of the same.

>       * making it formal part of the MOTU process to contribute patches
>         to it

    To date most formal MOTU processes seem to involve coordination
with others for review when making certain types of changes, rather
than requiring specific actions.  I'm not convinced there is a
sufficiently strong correlation between those interested in packaging
documentation and those interested in maintainance for a rule
requiring packaging-guide input to generate high-quality
documentation.

>       * asking new contributors to update the documentation of FAQ in
>         return for answered questions

    I've tried this method a couple times for wiki documentation, and
was not entirely pleased with the results.  I believe the cause of my
dissatisfaction was the difficulty of accurately explaining something
to which one has only limited exposure, combined with the difficulty
of maintaining volunteer motivation for a quality product in a
quid-pro-quo environment (it's especially hard to say how much
documentation work should be done for a given volume of answering
questions).

-- 
Emmet HIKORY