What are we doing wrong?

[Kyle Nitzsche]

Jim Campbell wrote:
> {snip}
> I think much of what you are trying to do can be done with a new Gnome 
> syntax, Mallard (see projectmallard.org <http://projectmallard.org> ), 
> or (evil of all evils) DITA.  Trying to hack something that is book / 
> chapter / article focused like DocBook into a more topic-oriented, 
> modular format doesn't seem like the way to go when there are other 
> options out there that can do what you want 
>
> DITA is really built to do what you are trying to do, but it is a PITA 
> (ha, get it) to author in (especially if you don't have any fancy 
> authoring tools).  Mallard is being actively developed, and is growing 
> in leaps and bounds.  It is super-easy to author in Mallard.  It is 
> easy to add plug-in style supplemental help (think docs for custom 
> plugins or OEM-specific content) in Mallard.  
>
> Shaun McCance is organizing a desktop help summit in Chicago in March 
> ( http://is.gd/6DS7x ).  Is there any chance that you can attend?  It 
> sounds like your Canonical-related documentation needs are kind of on 
> the leading-edge of where desktop Linux docs need to go, so it would 
> be good to get your input.  
>
> Jim

Hello Jim,

Mallard definitely sounds very interesting and I look forward to diving 
into this in greater detail. I would like to attend the summit you 
mentioned, and I probably will. Am looking at details now.

Regarding customizing ubuntu-docs content, I'd note that customizability 
concerns is a factor for ubuntu-docs, since Ubuntu is in fact frequently 
customized in many ways and we want to facilitate this.

That said, one can divide customization tasks into:
 * Adding content: I've heard Mallard enables that admirably. \o/
 * Modifying content: perhaps I am wrong, but this is a packaging 
question to which Mallard is inapplicable. That is, to modify content in 
a large package (like ubuntu-docs) one has to fork the entire package, 
which means you don't get updates unless you take manual steps. However, 
if the large package is divided into multiple smaller ones, then one 
only needs to fork the smaller one of interest and the other packages, 
since they  are not forked, continued to get updates as usual.
 * Removing content: again, this is a packaging question to which 
Mallard in inapplicable, I believe, but please correct me as needed.

I can imaging a future in which ubuntu-docs is:
1) Modular (package wise) to enable modification and removal of content.
2) Mallard content (where applicable - maybe everywhere?)

In this imagined future there is:
1) Identification of high-level requirements and risks
2) A plan to implement all requirements
3) A plan to mitigate all risks

I would expect it to be implemented in a stepwise fashion (not 
everything all at once), in order to limit risks and to provide 
learn-as-we-go opportunities for adjusting the master plan to new insights.

LTS+1! ;)


Cheers,
Kyle