Re: Making our documentation more cohesive

[Shaun McCance <shaunm gnome org>]

On Sun, 2005-10-16 at 10:15 -0400, Alexander Kirillov wrote:
> On 10/15/05, Brent Smith <gnome nextreality net> wrote:
> >
> > 2) Standardize the titles of each document by removing version numbers,
> > fixing capitalization, removing unnecessary articles and adding a type
> > to the title such as "Manual", "Tutorial", or "Guide".
> >
> > - Many documents have a trailing version number in their title.  I would
> >    like to remove this from all documents, since docbook provides an
> >    element, <releaseinfo>, to contain this.  Having the version number in
> >    the title is superfluous and distracting.  This will need to be
> >    changed in translations as well.
> >
> The version number is there for a reason. Namely, GFDL requires that
> "derivative document" must have a different title than that of the
> original document. Thus, if the document title is just "gedit Manual",
> no one  but the original author can make modifications and release
> under the title "gedit Manual". Having version number as part of title
> bypasses this problem.

So we actively chose a license that requires us to make documentation
that is unfriendly to readers?  Honestly, the sorts of requirements
the FDL has placed on us are ridiculous.

Anyway, I already changed some documents to have the sans-version
titles.  The way I see things, what I did was perfectly legal, since
I did change the title from the version I modified.  I changed the
title from "Foo Help 1.4" to "Foo Help".  Sure, maybe *some* version
of the document in the past had the title "Foo Help", but not the
version I derived from.

Unless, of course, some weird twist of legal logic forbids that, but
I would argue that that creates a NON-FREE license on the same grounds
that the old BSD advertising clause did:  It places undue restrictions
on people creating derivative works.  They have to check the entire
history of a document to make sure the title they use doesn't conflict
with a title anybody else used.

With version numbers in titles, we could argue that you just increment
the version number, thereby obviating any potential conflicts with past
revisions.  But what if you and I both made a derivative of the document
"Foo App 1.4"?  We'd both call our documents "Foo App 1.5".  Whatever
utility the FDL thought it was providing is now gone.

The FDL also has weird requirements on revision history, and the ways
in which we've abused DocBook in order to fulfill those requirements
are pretty insane.  Both of these problems boil down to the same thing:
These requirements are only for people other than the copyright holder.
The FDL is designed for the copyright holder to be able to produce
normal works, and for the *occasional* fork from other people.

The Gnome Documentation Project doesn't work that way.  We gets lots
of contributors (or, at least, we wish we did).  Every revision of our
documentation may add two or three new copyright holders, and those
revisions happen every six months.  Clearly, the version in CVS is
what we want to be the definitive, non-forked version.  It's what
*should* qualify for the FDL's implicit idea of a mainline version,
but it doesn't, because we don't have a single copyright holder.

Given these issues, together with the problems the Debian team have
had with the FDL, I think it's time we started investigating other
licenses for our documentation.  And we should choose a license that
allows us to write documents that conform to sane style guidelines.
I can pretty much guarantee that no professional style guides on this
planet will recommend putting version numbers in titles.

Technical limitations are a poor excuse for crappy output, especially
when those technical limitations are self-imposed.

--
Shaun