sec=unclassified RE: The value of separating the doc wiki

[Dan McGarry]

Jonathan Jesse wrote:
> 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

It's not at all uncommon for this to happen. Nor, in my opinion, is it a 
Bad Thing. As a project moves closer to each milestone, it's a good time 
to review how things went and to consider how things could improve. As 
long as everyone resists the temptation to push all those great new 
ideas into the imminent release, everything should be fine. 8^)

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.

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.

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?

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.

-- 
Dan McGarry		it.psl at fsp.org.vu

IT Consultant
Community Communications Project