Documentation email list?

[David]

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"

It could be done something along the line of the man page, which does
follow a rough format, even though the quality of the pages is very
uneven. If the format is well set, then anyone can write part of the doco
(even me!) and leave it to some more knowledgable person to complete.

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.

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'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.

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

On Fri, 1 Oct 2004, Jeff Waugh wrote:

> On Fri, 2004-10-01 at 10:12 +0100, Benjamin Edwards wrote:
> > There have been a few people
> > talking about documentation
> > recently. This is both regarding
> > online collaborative documentation
> > such as FAQ/hardware compatibility
> > and user/hot-to type things.
> >
> > I think ubuntu-doc at lists.ubuntu.org
> > would be great, or even essential.
> >
> > What do people think?
> >
> >
>
> Yes, great idea - I'll get this sorted out with a proper Ubuntu team and
> so on. :-)
>
> - Jeff
>
> --
> Ooh, ooh, ooh!             http://www.ubuntulinux.org/           Ubuntu!
>
> --
> ubuntu-users mailing list
> ubuntu-users at lists.ubuntu.com
> http://lists.ubuntu.com/mailman/listinfo/ubuntu-users
>