Reorganize MOTU team documentation?

[Emmet Hikory]

Morten Kjeldgaard wrote:
> I have to admit it: I hate the wiki. While it is very, very, very easy
> to add new and quite good looking documentation, it is nearly
> impossible to maintain, let alone get an overview of what is available
> and what state it is in.

    I've complete agreement with this, and a move to something that
was easier to use would be pleasant.

> Now, in connection with the reorganization of the MOTU team, I propose
> that all the MOTU team documentation gradually be moved into Mallard
> format in an ordinary directory tree, living in a bzr branch owned by
> our team on LaunchPad.

    While on the surface this seems like a good idea, and your
arguments are both strong and cogent, there are some remaining issues
that I believe need to be addressed, structural, technical, and
social.

1) With Archive Reorganisation, the vast majority of documentation is
no longer MOTU-specific, to the degree that aside from a basic set of
team pages (overview, roadmap, meetings (and historical minutes),
policy summary (mostly related to Leaders/Meeting/Council, etc.) I
don't think there's much that belongs under "MOTU Documentation".
Changes to "Developer Documentation" should be discussed on a wider
list.

2) Much of the Developer Documentation (and all MOTU-specific
documentation) tends to reference information for other teams: most
especially the various QA teams (bugsquad, testing, etc.).  Moving it
out of the wiki fails to help this integration, and makes it difficult
for those working on other teams (who may not have any reason to know
bzr) to easily reference our documentation.

3) Publication to a known URL is a huge advantage.  Aside from the
ease of passing URLs in IRC, such pages also show easily in various
web searches about a topic.  It is painful to extract an appropriate
current URI for a formatted page from loggerhead, so that is
insufficient as an alternative.  Regular updates to some known
authoritative provider would work, but there would need to be an
expectation of persistence for the length of the project.

4) The majority of our fellow developers are probably not familiar
with mallard.  While they can learn how to use it, it seems
unfortunate to make this change at the same time we are making other
changes that require developers to update their understanding:
frequent change of the way in which things are done has often been
cited in the past as a reason for developers to cease contributions.

    Of these, I think you have a sensible suggestion for #3 (although
it likely requires significant additional discussion to arrange for
that hostname to be recognised and autopopulated), but even there we
would need to set appropriate redirects for the pages in the wiki.
The remainder of the points need more thought and coordiation at a
minimum, and there may be additional items that some will raise.

    I'd like to see this be codified and easy, not lest because I'm
unhappy with the state of a number of pages where I've failed to keep
up with edits and discussions about why I'm rejecting changse, but I
think that we need to do this very carefully and ensure a minimum of
regressions in order for it to be successful, rather than being
ignored as a splinter project and leading to various heated
discussions six months hence.

-- 
Emmet HIKORY