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

[Stoffers, Robert LAC]

Renaming the tread, sorry for hijacking the wiki one.

> Part of me always wonders why every time we near the end of the release we
> start discussing on how we want to change everything.  Just prior to release
> of Breezy we had this discussion in regards to is DOcbook the way to go, why
> do we ship it this way, is the wiki to hard to understand and follow? etc,
> etc, etc


> I'm agnostic about documentation markup styles, as long as the markup 
> being used is well supported by tools that make data transformation easy 
> (or at least possible). I am leery though about markup styles that are 
> limited in the edge cases, causing inconsistencies to creep into the 
> documentation corpus. DocBook is somewhat immune to this (provided it's 
> used properly), but I'm afraid I'm not at all familiar Guide XML, 
> mentioned elsewhere in this thread, so I can't offer an opinion on it, 
> save to say that 'easy' things make me nervous.

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.

> Changing website layout is almost always a 
> darned-if-you-do-and-darned-if-you-don't proposition. I agree in 
> principle though that there needs to be a place for docco and all 
> official docco should be in that place. I worry though that this might 
> lead to a sense of exclusivity.

My idea gleaned from the Gentoo site actually has the opposite affect, it allows anybody with a web browser to "check out" a copy of the XML source, make changes and submit a patch (a one line command). This lessens both the learning and initial entry curves as most people already know how to use a browser and don't have to install/learn how to use svn/bzr. 

> Robert, you mentioned elsewhere in this thread that having more 
> accessible docco might lead to a reduction in the number of unofficial 
> documentation resources out there. Are you sure that's desirable? 
> Wouldn't we want a situation in which there are a plethora of online 
> resources of varying detail and accuracy, but all of which aspire to a 
> home on the official Ubuntu documentation site?

What I wouldn't want to see is a number of unofficial projects giving bad advice and breaking peoples systems. We experienced this with the ubuntuguide.org web site and many hours were wasted by IRC and forum users explaining how to fix systems that were broken after following such guides. The benefits of official documentation are numerous, such as ensuring the use of open systems and licences, accuracy and where that fails the *ability* to amend it directly. Of those benefits just mentioned, ubuntuguide.org was only using an open licence (GPL), aside from that nothing could be done to get it fixed and it kept on breaking systems (this is why the official Desktop Guide was born). 


> IMO, a community where people are welcome to write what they like and 
> how they like, and where they have a place to put it once it's matured, 
> would be a very healthy and happy thing. Perhaps Guide would help with 
> that. I don't know. I do know that writing good documentation can be 
> made *easier*, but it's never easy.

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.

--
Robert Stoffers
rob1 at ubuntu.com