Documentation email list?

[Benjamin Edwards]

I totaly agree.  I would say there may be a few templates/giudelines (with a lot of overlap) depending on wether in it a nrwbie doc, a technical doc etc.

In terms of documents being searchable I also agree.  I cant remember the last time I came across a decent searchable OS documentation project.  I think we should be talking about a document database whitch is properly structures.  this is partly what the tags thing I put up at http://wiki.ubuntulinux.org/TagsDefined is for.  I also think we should have a decent technical knolage base (will put up a proposal for this on the wiki this weekend (hopefully).

I would encorage you to start putting stuff up on the wiki, I have set up http://wiki.ubuntulinux.org/DocumentationArea.

Ben  

>>> David <david at kenpro.com.au> 10/01/04 02:08pm >>>

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 
>

______________________________________________________________________
This email has been scanned by the MessageLabs Email Security System.
For more information please visit http://www.messagelabs.com/email 
______________________________________________________________________


______________________________________________________________________
This email and any files transmitted with it are confidential. It is for the intended recipient only. If you have received the email in error please notify the author by replying to this email. If you are not the intended recipient, you must not disclose, distribute, copy, print, or rely on this email. Any views expressed by an individual within this email which do not constitute or record professional advice relating to the RNLI, do not necessarily reflect the views of the organisation.

Registered Charity Number 209603