Documentation, GFDL, etc.

Last summer I found myself delving into documentation writing & maintaining. My email client of choice, Sylpheed, which many FLOSS users might remember from early 2000’s when it was one of the first full-featured GTK+ clients (at least as far as I know), was distributed with a set of long-time unmaintained documentation that quickly became more or less completely out-of-date.

In fact, it wasn’t touched for over three years and was left in a state of partially completed LinuxDoc SGML to DocBook 4 XML migration. The first thing that needed to be done, even before finishing the migration and previewing the actual documentation, was obviously evaluating whether it is actually worthwhile for a new maintainer without deep knowledge of the given maintenance rules & processes to try to continue with updating the original documents, or whether it would be better to start from the scratch, i.e. with a complete rewrite.

Since I wasn’t feeling very adventurous and my previous experiences were quite limited, to say the least, I eventually sticked with the former option.

Now I can say that the biggest obstacle is not a need to understand DocBook 4, neither it is adapting work flow procedures and writing style of documents with numerous authors in their history, it is actually dealing with the GNU Free Documentation License, the license the said documentation is distributed under. I believe that many rants have been written before already about this piece of legal text, so I won’t repeat others here. Still, I’m quite grateful for Creative Commons licenses as something fresh and needful coming into scene and replacing GFDL within many documentation teams & efforts. I wish it was more feasible for maintainers to relicense a documentation work done by many (inactive and probably unreachable) authors from GFDL to CC. That being said, the clause that appeared in the GFDL version 1.3 is/was apparently not very helpful, unless you wanted to relicense content on Wikipedia or something very similar.

Anyhow, what I have found in my experience (IANAL) to be least amusing about GFDL is:

  • The idea behind invariant sections etc. (Yes, I can understand those good intentions that went pretty wrong, I would say.)
  • The definition of a transparent format.
  • The need for distributing the full text of the license along with a licensed document.
  • The thing that a generated HTML file with included GFDL copy (i.e. a generated file converted from DocBook XML source files) is or at least might be seen as an opaque copy, that is one needs to distribute a (plain text) file with full text of the license along with HTML file distribution (be it via tarball or any other standard channel). This issue was brought to my attention by Ricardo Mones and discussed on the Sylpheed mailing list.

Planet Fedora

So after crying my eyes out, I realize that this is my first blog post that might land on Planet Fedora, so I would like to say hi to all the hopefully interested readers out there! You can find most of my Czech localization & documentation writing contributions upstream, however, with me joining the Fedora Czech translation team ca. two years ago, and enjoying my encounters with the Fedora l10n infrastructure, notably the Fedora Transifex instance, ever since. Though I do remember the times when translate.fedoraproject.org was running a Damned Lies fork, also. OK, not too far away history, anyway.