re: [Doctable] Documentation Writing Process

["Dan Mueth" <dan eazel com>]

There have been a few side discussions going on, related to the DocTable,
the GNOME Style Guide (in development), and other miscellaneous things.  
They tend to fit together nicely and are of general interest, so let me
try to summarize some of them so we can move forward on this discussion
and improve our current document writing process.

WRITING INSTRUCTIONS
--------------------
We need:

1) The GNOME Style Guide - This should explain the GNOME writing style
including use of markup, appearance of figures and screenshots, use of
language, and other style to help writers produce good documentation and
to allow the body of GNOME documentation be self-consistant.  (Currently
under development by John Fleck, Alexander Kirillov, John Gilger, Pat
Costello, and John Sheehan.)

2) GNOME Word List - This should list all the terms we standardize on,
capitalization of them, hyphenation, and possibly definitions where it is
not obvious or there is a possibility for confusion or use of a term for
two different meanings.  This could be part of the Style Guide, although
it may be easier to keep them seperate initially.  (Under development by
style guide team.)

3) Example documentation/tutorial - We need one or more example documents
which illustrate good and bad writing and a tutorial which discusses
specific points in the example documents.  We might want to arrange this
as "A Tutorial on Writing GNOME Documentation" and put the example
documents in appendices.  Then the main tutorial would be a discussion of
these example documents.

4) The GDP Handbook should be updated to reflect these new documents as
they appear, and the new process we introduce.  (Dan)


NEW PROCESS
-----------
I'll try to briefly summarize some of the ideas which have been going
around.  The new process should be discussed and determined on this list.

Goals:
* Improved translatability
* Improved quality of documentation
* Improved QA process
* Improved consistancy in style, word use, overall appearance, etc.
* Improved ability to meet deadlines and ship the best documentation
possible

Some of the main things we need to do:
* Improve DocTable
* Add a content editor role.  The content editor goes through several
revisions with the author, starting at outline stage and moving toward
final product, to help the writer create documents which are structured
and written well.
* Add a copy editor role.  The copy editor views the document when it is
deemed finished by the writer.  Using the GNOME Style Guide, GNOME Word
List, a dictionary, and a good understanding of the english language, the
copy editor fixes any mistakes in grammer, spelling, inconsistant word
use, etc.  In most cases this is just a long list of very minor changes
which may not require discussion with the author.  In some cases,
the changes are less trivial and require discussion with the author.
* Add an indexer role.  A la the index at the back of a book.
* Add a QA role. Quality Assurance is a good thing.
* Write/update the documents described in the previous section.
* Keep a list of people for each role (content editor, copy editor,
etc.) on the GDP web page.

I see this as a fairly linear process in which we can specify milestones:

Milestone 1: "Document Assigned to Writer and Content Editor"
Here we just need a writer and a content editor to each assign themself
to the document in the DocTable.

- After this milestone, the writer writes the document.  The writer should
pass his/her work to the content editor for review at several stages in
the process, starting with the outline, and ending in the final
product.  The writer may also get feedback from other writers or editors
and from the application developer(s) to guarantee the document is
techinically accurate and written clearly.  (We do the latter now,
although the addition of the content editor should be a big help.)

Milestone 2: "Document Written"
The writer and content editor are finished with the document.

- After this milestone, a copy editor should assign himself/herself to the
task of copy editing the document.

Milestone 3: "Document Assigned to Copy Editor"
The copy editor has assigned himself/herself the document in the
DocTable.

- Now the copy editor should copy edit the document.  For simple changes
like spelling, grammer, word usage, etc. the copy editor changes the
document without consulting the author unless the change may change the
meaning.  In cases where the change may change the meaning or the change
may be considered drastic, the copy editor should contact the writer and
content editor to discuss the change.

Milestone 4: "Document Copy Edited"
The copy editor is finished.

- An indexer should assign himself/herself the document in the DocTable.

Milestone 5: "Document Assigned to Indexer"
The indexer has signed up in the DocTable.

- The indexer works black magic to produce an index for the
document.  Any writers or editors who try to change the document during
indexing may be turned into a newt.

Milestone 6: "Document Indexed"
The index is finished.

- An "integrator" should assign himself/herself to the document in the
DocTable.

Milestone 7: "Document Assigned to Integrator"
An "integrator" (bad name - what should we call this?) assigns himself or
is assigned the document.

- The "integrator" now puts the final version in CVS if it isn't already
there and makes any other changes necessary to the build system and
software.  This may be a GDP member who is in charge of doing this for a
given module or it may be a hacker who works on the application.

Milestone 8: "Document Integrated"
(you get the picture...)

Milestone 9: "Document Assigned to QA"
(...)

- QA means making sure the package builds and installs fine, all the help
buttons and menu items pull up the document using the correct browser, all
screenshots are installed and displayed properly, the document is rendered
properly by the browser, etc.

Milestone 10: "QA Done"


So we have quite a few roles:
1) writer
2) content editor
3) copy editor
4) indexer
5) integrator
6) QA

While some of these roles may overlap, each document should have different
writer, content editor, and copy editor.  Generally we want to avoid
having the same person do multiple roles for a given document - the more
eyes that look at a document the better.

Translators ideally will not start until the indexer or integrator is
finished.

All feedback is welcome.

Dan