sec=unclassified Website Documentation (Was: The value of separating the doc wiki)

[Robert Stoffers]

Matthew East wrote:
> 
> Jonathan and Corey are 100% correct: we are nearing the end of a release cycle
> and really do not need talk of drastic changes at this stage. We've got work to
> do. I'd like to join the people who call for time being spent on making the
> documentation great, rather than ideas. A time for ideas will come later.

The idea isn't to draw people away from the docs, don't get so worried 
Matt! This is merely a discussion, nothing is even looking at going 
ahead just yet, and even if it did I would wait until after the next 
release.

> Having said that, in my view there is no chance of moving away from docbook xml
> as a documentation format, the main reason for this is that GNOME documentation
> is in this format and I believe that in the long run Ubuntu desktop
> documentation and GNOME documentation will get closer and closer together.. 

Whist it's nice that GNOME chose whatever, don't forget that Ubuntu != 
the GNOME project. The doc-team is free to use whatever tools it likes 
to achieve its aim. I fully support the use of Docbook, however there is 
no need to completely ignore everything else that exists. Lets not 
forget that GuideXML can be converted up to Docbook also.

> 
>> That's why we have, and will continue to have the wiki for unofficial
> community guides/docs. There is no
>> reason why some of the more mature, useful ones couldn't be made "official"
> and be given the docbook/guide
>> XML website treatment.
> 
> The distinction between official and unofficial is totally misleading both for
> the user and for contributors. The use of these words also creates division. The
> key word I'd like to see used is "reliability". The reality is that the wiki
> contains a number of guides which are equally as reliable as the documents we
> take care of, in some cases more reliable, and in some cases less. A website
> where the user can find *all* documents is what we need, and good quality
> control/reliability assessment to ensure that the user knows what he is getting. 

I think your reading a little to much into what I said, none of my 
suggestions will make anything more or less official then what they 
already are. What my suggestions will do is open up the contents of the 
doc-team subversion repository to a wider audience, meaning more eyes 
and hands looking at/contributing to the core Ubuntu documentation. The 
advantage over the wiki is that the system is still controlled by the 
doc-team, which ensures a higher level of reliability over other sources.

> 
> Gentoo have a good system too, but Gentoo is a different world where technical
> and high quality documentation abounds because of the nature of the user base.
> We're in a different situation, in my opinion, and can develop a system that
> best fits our user and contributor base.
> 

I agree 100%, I think we could develop a system that best fits our needs 
too. All of my observations were originally based on what I saw on the 
Gentoo side of things, and put forward to entice discussion on the idea.

--
Robert Stoffers
rob1 at ubuntu.com