more defined process

[Tammy Fox]

On Fri, 2004-08-13 at 13:38, Dave Pawson wrote:
> On Fri, 2004-08-13 at 18:02, Tammy Fox wrote:
> 
> 
> > If you are chosen as an editor, your name is added to the project page,
> > and your job is to wait until writers are finished writing the tutorials
> > and need editing.
> 
> ? How do I get chosen as an editor?
> What's an editor do? (Paul/Karsten)
> How often do 'writers finish a piece'
> 
> Bit of a drop off there?
> 
> Fill in please,
> but yes. good basic intro.
> 



That's why earlier it says that the role definitions are still being
defined. I'm trying to develop the process and the roles at the same
time to speed things up.

My thoughts on how to get chosen as an editor: you submit a description
of your experience as a writer, editor, and user of DocBook to the
project lead along with a brief description of your technical skills. I
can put together a form that allows people to submit the same
information.

I'll share some guidelines I developed when I was tech lead of the RH
docs:

*Before* the writer hands a document over to the editor, he/she must
verify the following:

1. Spell check all files
2. Verify that all URLs are still valid
3. Verify that the technical content is correct -- which means follow
your own documentation step by step to confirm
4. Verify that the names of the files include the language such as
example-tutorial-en.xml
5. Verify that all sections have an id so all HTML files generated have
static filenames
6. Verify that all ids following the naming convention in the Docs Guide
7. Checkout the fedora-docs CVS module if you haven't already, and   
   verify that if you drop in your directory that it builds within the 
   CVS environment, including using a Makefile based on the existing    
   ones
8. Verify the HTML Output:
   a. Click all links to make sure they are valid
   b. View each page to make sure there aren't any missing images.
   c. Make sure all the images match their description in the text.
   d. Click the Legal Notice link on the title page to make sure it   
      works and contains the FDL, that the version number has been 
      bumped if a previous version existed, and that the last modified 
      date has been updated.

Then, the editor is responsible for:

1. Making sure the writer followed the docs conventions including using
standard id names, verifying that the parent file follows the example
tutorial so that it builds in CVS, and proper use of XML tags.
2. Checking the grammar and word usage
3. Verifying that it is written for the intended target audience
4. Looking for any possible missing steps (While reading, if it feels
like a step was omitted, ask the writer to make sure. Many times writers
who are familiar with a procedure will leave out a step that is obvious
to them but not to the reader.
5. Verifying that it builds in the CVS structure
6. Determine if the topic needs a second technical review. If it does,
work with the writer to email the mailing lists to find someone to
follow the document step by step to make sure it works on their system
as well.

> (needs the 'sales pitch' too. WE REALLY REALLY NEED MORE DOCUMENTATION.)

Anyone have anything to add? Thoughts?

Tammy