GNOME FAQ FUBAR'd; need advice

[Todd Graham Lewis <tlewis mindspring net>]

Ok, I completely screwed up the transition of the GNOME FAQ from
v1.0 to v1.0.1.  This was supposed to be a simple little release,
but, as I mentioned, it is F'dUBAR.  This is, I think, an opportunity
to examine how to deal with a complex and fluid document like this
in the presence of multiple translations, and I would like to hear
people's ideas.

1) HOW THE FAQ IS SCREWED UP

When I released v1.0 of the FAQ, I hand-edited the SGML to make it
as pretty as possible.  If you look at the source code for the v1.0
SGML version of the FAQ, you will see that the paragraphs are nicely
justified, etc.  The problem is that I then went on my merry way
editing the LyX version for the v1.0.1 release.  When I spit out
the SGML for v1.0.1, although it had the exact same words as v1.0,
it bore no structural resemblence to it, and a diff between the two
is full of meaningless differences in formatting.

This makes it very hard to catalogue the changes which I made and
send them out to the translators for them to integrate.

This was colosally boneheaded on my part.

2) HOW DO I WANT FOR THE FAQ TO WORK

	A) I would like for each individual change to the FAQ to be
	catalogued.

	B) I would like for these changes to be easily accessible to
	the translators so that they can apply them to the various
	non-English versions of the FAQ.

	C) I would like to track the changes which the translators make
	to their respective versions of the FAQ, so that I can understand
	how close they are to the English version.

	D) I would like _not_ to do a release of the FAQ until my
	version and _all_ of the translations are in sync, so that
	non-English-speakers are not given worse information than English
	speakers.  Of course, this is dependent on the availability
	of translators.

	E) I would rather feed the translators a steady stream of small
	changes rather than a big group of changes, so that they can
	better schedule the time out of their lives that they spend
	on the FAQ and not have to rush all of the changes into their
	translations at the last minute to allow me to do a release.

3) WHAT DO I PROPOSE WE DO WITH THE FAQ?

I propose to build a small computing system to accomplish these goals.
What I envision is similar to CVS.  I would use CVS, except that I
know of no way in CVS to document whether one file has been brought
into accord with another file.  (E.g., has 4.1.6.es been updated
to reflect the changes that happened two weeks ago to 4.1.6.en?)
Fortunately, this is a very simple project, and I am confident that
I can build it.

What the translator would see is a utility.  This utility would list for
the translators a list of questions which have changed.  The translator
selects one of these questions.  The utility fetches the old and new
versions of that question and presents them, as well as a diff between
the two, to the translator.  The translator then updates his translation's
version of that question.  The system then takes that question off of
the translator's TODO list.

The way that I propose storing the FAQ is in a two-pronged directory,
FAQROOT.  The first prong is $FAQROOT/questions.  Under this directory
are 'n' directories, where 'n' is some number.  Each of these directories
stores a single question/answer pair.  It stores one version of the Q/A
in a file per language.  Thus, e.g., a single question's directory
would look like this:

$FAQROOT/
   questions/
      43/
         en
         it
         es
         fr

'en' stores the english-language version of the Q/A, 'it' stores the
italian version, etc.

The second portion would be the structure portion.  This would have
all of the sections, subsections, etc., of the FAQ, with symlinks
to the actual questions in the $FAQROOT/questions portion.  This
would look, e.g., something like this:

$FAQROOT/
   structure/
      3/
         TITLE.en
         TITLE.it(...)
         INTRODUCTION.en
         INTRODUCTION.it(...)
         2 -> ../../../questions/412/

This way, I can change around the organization of the FAQ without
the translators having to care about it.  Any changes to a section's
title or introduction would be tracked the same way as the questions.
Perhaps I should store these in the 'questions' tree, which might
be better titled the 'content' tree.

I would track all actual files using RCS/CVS, enabling one to see
the history of changes thereto.

IMPORTANT: The content files themselves would be SGML fragments.
They would have tags like "<ITEMIZE>", but not like "<SUBSECTION>".
Translators should be able to keep the tags like they are in the
English version and just translate the actual content.  It is
important, esp., that cross-references be left alone, in order
for the document to remain integral.

What do people, translators in particular, think of this approach?
I would like to start work on it, but I don't want to do it if 
someone has a better way, or if someone has a big objection to this
approach.  Please let me know what you think!

--
Todd Graham Lewis      MindSpring Enterprises    tlewis@mindspring.net
 The Windows 2000 name was obviously created over a glass of root beer
  in the company cafeteria by a couple of executives looking for a way
   out of the Windows NT delays.                     -- John C. Dvorak