Reorganize MOTU team documentation?

[Daniel Holbach]

On 02.03.2010 00:01, Emmet Hikory wrote:
> 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.

Agreed.


> 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.

This could theoretically be solved by checking out current documentation
trunk and publishing it as HTML somewhere.


> 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.

Before we decide to do this it might make sense to talk to people who
did this work in DocBook before and how many people enjoyed contributing
there.

I don't mean to be too negative and am happy about every attempt to
spruce up our documentation, but I have some reservations about the ease
of doing drive-by fixes or writing a new article.

Have a great day,
 Daniel