Documentation email list?

[John Levin]

On 1 Oct 2004, at 14:08, David wrote:
>
> Might I suggest that before any new docos are considered, there be a
> discussion on "templating" documentation, so that anybody who writes 
> docos
> knows what should be included and how it should be done. In other 
> words,
> the first documentation should be "HOWTO write documentation"

I disagree to a certain extent, based on memories of the mozilla 
documentation newsgroup some while back (18 months ago?) where things 
slowed down to a crawl due to endless debates over standards and 
formats, and trying to pre-empt every possible problem (an impossible 
task!). I think the best way of learning is by doing, and then, in true 
FLOSS style, testing and  bug-hunting.

Of course, this doesn't mean there shouldn't be a plan, priorities, and 
a set format (docbook?)

> <snip>
>
> One item that should always be included in any decent doco is a set of
> examples. Another item is a glossary of terms.. what the hell does TLA
> stand for? perhaps a consolidated glossary might be a good idea.
>

There are a number of glossaries knocking around the net - the problem 
is where to find them, and how to evaluate them. Simply consolidating 
them on the ubuntu doc site (and perhaps tweaking to make it Ubuntu 
specific) would be an important first step.


> The biggest failing of computer doco is either:
>
> a) incompleteness.. several steps left out because you are supposed to
> just *know*, and
>
> b) too cryptic, on the assumption that of course you know how to do it,
> why else would you be looking up docos, and of course you know what 
> every
> term and abreviation means because.. well... you just do!
>

I'd add: outdated - not revised as often as the code
and: difficult to locate - there's some excellent material spread 
around the net, yet not bundled in with the app, or referenced from the 
home page.

(I hereby propose that a HOWTO: google should be a top priority.)

> I'm sure lots of people do what I do, which is to have my own private
> cache of HOWTOs developed over years of suffering from inadequate
> documentation. I would be perfectly happy to contribute these to a 
> central
> project where they are accessible to everyone. I'm sure I'm not alone.
>

Yup. And it would be good to work with the documentation writers on 
other projects - with the mozilla/firefox community for example.
Just as code can be tweaked and reused, so can docs.
Perhaps a page on the wiki can be made for links to good but obscure 
documentation that we can work upon and revise? (Licenses checcked, of 
course)

> One last thought. Any documentation project MUST be searchable. I'm 
> amazed
> to find that the gnome desktop help isn't searchable.
>

Seconded.

John