Documentation Standard (was: Re: [Twisted-Python] Documentation.. On a wiki!?)

[Glyph Lefkowitz]

There is a place for wiki, but I don't think it's the same as a place
for docs.

However, since I don't think I've said it on the mailing list yet, I'd
like to state that my official position on the issue of documentation
standards is that there is no documentation standard until somebody
decides to make one.

Personally I think I'm going to work in LaTeX or maybe DocBook when I've
got some time.  However, if you want to submit some docs, please submit
them in any format that you feel like: content is more important than
format right now.

Whoever submits the most quality docs the fastest (and this is
essentially an arbitrary decision on my part, I know) will become the
documentation maintainer and I will use whatever format they used for a
standard.

That said, I'd like to recommend against wiki for the following reasons:

1: it's not set in stone.  Users will come to it and it may be different
than what they expected.

2: It tends to collect editorial annotations, and there's no structured
way to remove them easily.  This will be confusing.

3: Partially because of 1: and 2:, Wikis are good for tightly knit
communities, but what we need is external, end-user documentation, that
will be read by people with no knowledge of how the system works

Wiki might be a great way to get the documentation process started, and
a good place to publish drafts, but we already have IRC and cryptic
references to the mailing list -- we need something that's a more
gradual, high-quality introduction.

On Mon, 2002-02-11 at 18:40, Andrew Bennetts wrote:
> On Mon, Feb 11, 2002 at 02:46:39PM -0500, Christopher Armstrong wrote:
> > So, the idea is to use MoinMoin for Twisted's documentation. I have the
> > skeleton ported as well as one or two docs (and I'm working on
> > transcribing the rest of the docs to fit this framework). So, this is my
> > official submission for "what should Twisted use for documentation?". 
> 
> Interesting idea.  It's probably the most convenient format for quickly
> writing nicely structured docs, and it is structured enough that you could
> probably do a sane conversion to something else later, if desired.  In
> short, I like it.


-- 
"Cannot stand to be one of many -- I'm not what they are."
        -Guster, "Rocketship"
                glyph lefkowitz; ninjaneer, freelance demiurge
    glyph @ [ninjaneering|twistedmatrix].com
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 232 bytes
Desc: This is a digitally signed message part
Url : http://twistedmatrix.com/pipermail/twisted-python/attachments/20020211/a1cd152d/attachment.pgp