Using elvis?

[Paul W. Frields]

Some musings follow...

[...snip...]
> 2. What should be in there _right_now_ that is not?

An installation guide. A getting started guide. (Names generified from
the Red Hat documentation. We want the same thing here, only FDL'd of
course.) More TBA.

> 3. What bugs are there to fix in the existing documentation, so
> contributors can start working on them?

I am seeing the existing documentation as consisting of:

documentation-guide
developer-guide
example-tutorial

The install-guide is basically only a placeholder now, with an outline
for things to write.

I used the existing documentation-guide to learn the tools, and can
vouch that it and the example-tutorial are at least usable in their
current state. The bug(s) I filed were mostly cosmetic and not
showstoppers. The developer-guide has a bunch of FIXMEs inside, so may
not be quite ready for prime time yet.

> 4. What should be on the fedora.redhat.com/docs pages _right_now_?

At least *ONE* substantial tutorial document that is both:
(a) not of excessive length, and
(b) marked up in an editorially-approved manner (q.v. below).

> 4.1 How are we going to manage multiple documents across multiple
> versions?  The left hand navigation bar is going to fill up pretty
> quickly at this rate.

Ouch. I'll go out on the "ignorant limb" here since I am not a
developer. I assume you're talking about dealing with
install-guide-en-FC3, install-guide-en-FC4, foobar-tutorial-FC3,
foobar-tutorial-FC4, etc.... Whatever we use, it should have a ready Web
interface, easily organized, not impenetrable to a newbie, and hopefully
leading to docs easily read online, in addition to being downloadable
and locally-buildable. 

I've been playing with Subversion lately to tackle a project at work; I
don't know if that's the kind of answer you were looking for. Subversion
(hereinafter SVN) deals with trunk/tags/branches which makes handling of
multiple releases (branches) and the main code (trunk) somewhat less
unwieldy. We'd want to use more friendly names, of course, that make
sense to a Fedora newbie browsing the docs, since SVN's "trunk" doesn't
make much sense to people who aren't coders. I would think we could
customize SVN (or use something else in front of it) to produce spiffier
Web pages for mass navigation and consumption.

One last related point: I'd like to suggest, as far as approval of
documents goes, that at least two editors approve a document, with at
least one of those editors coming from inside the Fedora Project (Red
Hat?) "walls." I think that would give a consistent feel with the
traditionally high quality of official Red Hat documentation.

-- 
Paul W. Frields, RHCE (hoping that RH doesn't revoke on
                       grounds of "being an idiot")