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

[Jonathan Jesse]

> 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
>
>
>
>
>
> --
> ubuntu-doc mailing list
> ubuntu-doc at lists.ubuntu.com
> https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
>
>
I think with the focus that Ubuntu has on making sure things move
upstream, the documetation may slowly move some upstream.  Here is an
obvious example: Adept Guide.  In Breezy it started out as a Kubuntu
package.  As soon I get a chance to update it for the latest changes it
will move upstream to the KDE docs level.  A reason to stay with the
system we have is for projects such as this.

Jonathan

-- 
Jonathan Jesse