Using elvis?

Paul W. Frields paul at
Fri Jul 30 22:28:02 UTC 2004

Some musings follow...

> 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:


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 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")

More information about the fedora-docs-list mailing list