documentation process

[Karsten Wade]

On Sun, 2004-09-05 at 06:07, Rahul Sundaram wrote:
> Hi
> 
> I have been in the LDP list for sometime and the
> review process there is something like this
> 
> * Author submits the document link to the discussion
> list
> * Peer review is done by volunteers in the list
> * If the document is generally agreed upon to be
> included  the author would then update the document
> according to peer reviews
> * The document would be assigned to editors who would
> then do a language review as well as a technical
> review( need not be the same person).
> * It is included in LDP and goes through a yearly
> review to make sure its relevant and kept updated.
> * If not the document author is contacted off list and
> gently advised to make appropriate updates
> * If the authors cannot maintain the document it is
> moved to the unmaintained list or someone else takes
> over the maintainance or even completely removed where
> it is deemed necessary(gross inaccuracies or such- ex:
> kernel howto)

Thanks for the benchmarking information.  It's nice to see that we are 
following good practices.  I think the current FDP process (that Paul
provided links to) is relatively similar to this, with one important
exception.

By having a formalized editing process tied into the Fedora release
schedule, we keep a much tighter control on the quality and aging of
documents.

In Fedora, a year is too long to wait, and a gentle nudge is not
sufficient.  We need authors who are committed to maintaining their
documents and are prepared to do a proper hand-off to a new maintainer
or proper closure of the document, should the original author decide to
no longer maintain it.[1]  We definitely do not want documents thrown
over the transom.[2]

Another benefit to having a tighter author/editor connection is that the
documents can be honed to nearly perfect accuracy for Fedora.  TLDP are
working in a more generic realm; it's difficult for them to ensure total
technical accuracy, and documents need to be written to cover multiple
distros.  Their documents are generally very useful, but not often
specifically useful to each person's unique case.

For FDP, we can and should be 100% accurate when it comes to describing
Fedora in our documentation.  We can do this because the authors,
editors, and users are all on the same version of the same distro.

FWIW, the methodology you describe is appropriate for TLDP.  Their scope
is much wider; changes to generic Linux happen over a longer period of
time, where Fedora docs needs to closely track Fedora versions.  Our
process is at least three times faster.

- Karsten

New experiment in putting my lengthy asides ... well, aside:

[1] Yes, I know we'll have abandoned documents; we'll deal with that,
that's inevitable.  Even at a company, people leave and you can't
replace them in time, a document may go a cycle without significant
maintenance.  We must strive from the beginning to not invite documents
that will languish and die.

[2] For those who don't know this one, writers in the earlier part of
the twentieth century would sometimes throw their completed manuscript
into the open transom over a locked door, hoping that when a
publisher/editor (literally) stumbled over it the next morning, it might
be a step closer to being published.  The difference between a
publishing house that will print anything that comes in "over the
transom" and one that only prints work properly submitted and approved
is what I am alluding to in this metaphor.

-- 
Karsten Wade, RHCE, Tech Writer
a lemon is just a melon in disguise
http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115  5F1B D992 0E06 AD0E 0C41