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

[Matthew East]

Stoffers, Robert LAC <Robert.Stoffers <at> defence.gov.au> writes:

> Take a look at the link I provided in an earlier post. Suffice to say that we
could still implement the "easy
> contribution website" idea using Docbook, Guide XML however is just much
easier to learn.

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.

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. There
may come a time when there are good enough docbook->wiki->docbook tools that
work can be done directly on the wiki, although that time hasn't arrived yet.
For now, docbook isn't so hard to learn for those who are interested, and we can
also work to help people to contribute in other ways, via the wiki/sending us
material directly, etc.

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

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.

Matt