Matthias Warkus (mawarkus@gnome.org) – March 15th, 2005

Writing About GNOME

Given that I am not a “real GNOME developer” but rather some weird kind of promo person, writer and general nuisance (No, I do not want to be a consultant. Not yet.), I decided to write about what I think I do well. I hope you will find the following eclectic musings on GNOME-related writing vaguely interesting. As I have written a bound GNOME developer's manual , I focus mainly on de­veloper documentation here and I usually have longer, printed texts in mind, but most of what I write here should apply not only to fat programming handbooks, but other texts as well.

Different sorts of texts

There are many kinds of texts you might want or have to write about GNOME, both in print or on the Net:

Magazine articles (e.g. on new releases)

User documentation (book, article or on-line help file)

Developer documentation (book or article)

Design documents (white-papers, design guidelines, technical specifications)

...

Obviously, documentation is the most important area, and the one I am going to concentrate on. This includes documentation shipping with the software as well as third-party works.

User documentation

Arguably, the most ubiquitous documentation is user documentation, and it is also probably the most difficult to write well--especially if you are the developer, in which case writing the user manual for your own work has traditionally been the recipe for maximum disaster). For a long time, user documentation used to come in form of fat, printed manuals, often divided into a tu­torial and a reference. Those have been completely replaced by on-line help, which goes double for free software, which is generally not shipped in shrink-wrapped cardboard boxes.

The idea that what you are writing is a sporadically-consulted on-line help document is some­what dangerous. It is pretty simple to type up a kind of glorified bullet list of menu-entry and key-binding definitions and throw some token screen shots in for good measure. The attitude that a well-designed pro­gram will not need any user documentation at all is as popular as it is wrong, but certainly no program will need that kind of user documenta­tion. I have heard the opinion that GNOME's help is often a lot like this, which is probably exag­gerated, but not ex­actly wrong. Keeping in mind the idea that the whole thing should make some sense as a book, too, may help avoid this. (Here, the UNIX way might for once not be all that wrong: Classic manual pages were al­ways meant for pretty-printing as well as for on-line perusal.)

User documentation should be organised around use cases, not program features, but that holds true for all kinds of documentation. Because it is written for a (usually) non-technical audience, good style and avoidance of gratuitous tech-speak are probably more important than in developer documentation.

Developer documentation

That does not mean developers will like bad prose and superfluous technobabble more than users. They will probably tolerate it better, though. Another superficial difference is that de­veloper documentation will usually contain less screen shots and be much harder to typeset be­cause of all those pesky long identifiers.

There's also usually more to memorise in a developer's job than in a user's job. (Unless we're talking about highly complicated applications being used to their full extent, such as in CAD/CAM, which could be argued is some kind of development anyway.) This means your book will probably not only be used while climbing the learning curve of whatever you're discussing, but also as a desktop reference later on. While a good index never hurt any book, for a de­veloper's manual it's of even more importance than for a user's manual.

Then, what makes developers developers is that they're a technical audience and do not like to be thought of as non-clever. I think the biggest problem writing good developer documenta­tion is to be informative and complete without being patronising; and this requires a good guess at the expected technical proficiency of the audience. This can go wrong. I've seen an in­troductory book on Java recently that started out explaining what a programming language is, how the binary system works and other similar basic issues. The idea is not bad, but: This will bore or even anger the experienced reader, and, because none of the examples inside made use of bit fields or other constructs that require knowledge about binary, it patronises even the inexperienced reader, as the point of a Java book is to teach Java, full stop.

The decision about what readers can be expected to know beforehand is extremely important.

Design decisions

There are many other design decisions specific to writing about software, technical ones and more general ones. An example for a technical design decision: In my book I decided not to dis­cuss any accessor/mutator methods for GObject attributes that can be accessed through the property system. In a more general vein, I decided not to include any exercises or questions to the reader at the end of each chapter, as my experience is they will be mostly ignored anyway.

There are, however, some large-scale decisions to be made.

Two different overall approaches: Tutorial versus reference

As mentioned before, software often used to come with two manuals, one tutorial, one refer­ence. Some probably still does. Third-party documentation sometimes also comes as this kind of pair, e.g. Addison-Wesley's Red Book and Blue Book on OpenGL.

Though a reference is considerably easier to write than a large-scale tutorial, it is also much more tedious as it basically involves grinding through a list of UI elements (i.e. menu entries and dialogue widgets) or API elements (i.e. classes, properties, some methods and utility func­tions) and writing a standardised description of each. For GNOME, the in-line gtk-doc documenta­tion helps you here; many GNOME components thus come with fairly complete ref­erence material already. (I have always wondered whether there is a market to reach by editing and proofreading the stuff and selling printed copies of it. Some people apparently think so. Stay tuned.)

If there is any kind of excitement to find in writing software documentation (except the inevit­able unearthing of bugs in what you are writing about), it can be found in writing tutorials. However, it is very easy to write useless tutorials, too. I have tried writing a good tutorial by learning something I did not yet know (GNOME programming) and simultaneously writing about it. The problem is one can do that only once, and it has got to work immediately or not at all.

Accompanied-project vs illustrat­ive examples

There are basically three kinds of code examples in developer documentation:

Snippets illustrating one single feature, often in only one line;

Short examples

Full listings of non-trivial programs

Probably, no good book or article will work without snippets. Full listings, on the other hand, are of questionable use unless extremely well-commented, in which case they can usually be made into a mixture of short examples and explanatory text. Today, the full code for example pro­grams is, as a rule, available to the readers, either on an in-book CD-ROM or on the Net. There is no obligation to let every line of code in an example program appear in print.

The question is now--especially in larger publications—whether to use small, self-contained ex­amples, each illustrating a section of text, or show excerpts of a larger application. As the latter will usually imply that a simple example is developed into something more and more complex each section as increasingly advanced features are introduced, I call this the “accompanied-project” approach as the publication takes the character of a running commentary on a soft­ware development project.

It is, however, rather difficult to find a realistic, middle-sized application that can be continu­ously developed using increasingly complex API features and will do something meaningful at each development stage. Classic programming tutorials tended to feature some kind of data­base application such as an address book, which at the end of the book usually came out with ridiculously overblown UI and no back-end performance to speak of.

In my opinion, it is not only easier, but also more sensible to use illustrative examples, even if the beauty of the accompanied-project approach is hard to deny. There are combinations of both, e.g. using a number of small accompanied projects in parallel or one per chapter.

By the way, this particular design decision also somewhat applies to user documentation, with step-by-step instructions and/or screen shots in lieu of code examples. Especially for very fea­ture-rich software such as office packages, larger project examples may make sense.

Elements of style

As GNOME is an international project and our backgrounds are so diverse, I can only guess what advice on style you have been given during your education. If you are like me, you never heard anything at school about the things that make really good style, especially in technical texts.

The first rule about good technical writing is to forget about avoiding repetition by using syn­onyms, no matter how much they taught you not to. The same thing should be always be de­noted by the same word. (This is also the first rule of good journalistic writing, and constantly ignored by the frustrated middle-aged writers working exclusively for bad local newspapers.)

And one of the most important rules about good writing of any kind is to get a feel for period lengths. Any text is sectioned into a sequence of periods by punctuation. (By the way, it is es­sential to make good use of the semicolon. Many people never use semicolons because at school, they were not taught how to.) There should be a kind of softly alternating rhythm to the lengths of these periods—try to imagine one of those goofy balls that some karaoke machines display bouncing along the text from comma to comma, from full stop to full stop. It should be pleasing and relaxing to look at this imaginary ball.

Non-flat text and the problem of visual noise

In the same vein, but on a higher level, it is important to avoid lots of tight running text, as it scares the reader, unless you are writing a novel. Try to use enumerations and bullet lists a lot. (Know the difference: Use enumera­tions for sequences of actions and for lists where you have mentioned the number of items be­forehand. Use bullet lists elsewhere.)

Usually, in books or articles, there are ways to format 'boxed items' such as “reminders”, “warnings”, “notes” or “excursions”. Use them, but not excessively. For example, if the inner logic of your text dictates to put four warnings on the same page, change the inner logic. The cleverest of plans does not justify forcing any visual noise upon the reader.

The same goes for margin items. In my book, I first tried marking up every new function in the margin. To not make them too noisy, I later collapsed blocks of similar markers into one using wild cards. Probably the margin is still too noisy, though. Visual noise is also of concern with special symbols. Marking certain kinds of identifiers or references with a certain symbol or bullet can make pages with lots of identifiers or refer­ences uneasy to the eyes.

In my personal experience, technicians, especially hackers, are prone to overuse mark-up ele­ments such as special typefaces, references, symbols, boxed items or margin items. This is probably because always and consistently using a certain element when a certain case applies is more important to them than the look of the final text. Bear in mind that user-friendliness is the top priority not only in pro­gramming, but also in non-fiction writing.

Code examples

One of the recurring problems I had writing the developer's manual sounds al­most too trivial to be mentioned: Fitting the code examples in 55 columns. This is extreme; usually, listing environments tend to be a little wider; but even 60 or 65 columns is narrow compared to the standard 80, and much GNOME code exceeds even that by a large margin, as many GNOME API identifiers such as function names, ID macros or casting macros are very long.

You can cope with this in the following ways (in C):

Indent in small steps; keep tab width down to 2 or even 1 column

Format long function calls LISP-style, breaking the line immediately after the opening paren­thesis and making the arguments an indented block

Break long text constants at spaces (using backslashes)

Break long expressions at operators

The need to keep listings narrow can be an incentive to code in good style, and also a reason to select illustrative examples instead of an accompanied-project example. What you should abso­lutely, positively never do is simply break all over-long lines at the margin using backslashes, as this is prone to destroy all readability and make your listings look like filler.

In a good book or article, you want your listings to be read just as much as the running text, if not more. Their style should be at least as good. This is also the reason why choosing a very small and/or condensed typeface for listings--which was common in the 1980s and is probably still done in a lot of books, though it has gone somewhat out of fashion--is not really an option.

Screen shots and other illustrations

An abundance of screen shots might look like even more like filler than copious code examples. There is no easier way to expand a book by hundred or two hundred pages, but the question is whether that will do anything for your readers. I recall user handbooks with screen shots cover­ing the top half of every page and explanations below. I think that was in the same time when books with full-colour screen shots became in fashion for a short while. Maybe doing it in this excessive way may work. But usually, you should keep the number of screen shots low, and crop them well. Full-screen shots are pretty much useless in most cases; what's interesting is usually one specific window or even a small portion of one window.

The filler problem is the same for graphical illustrations of other kinds. UML inheritance dia­grams for every new class introduced make a programming handbook thick, but, let's face it, one big tree diagram in an appendix should suffice. The overuse of UML in some programming documentation minds me of how some DP textbooks used to come with both a flowchart and a hectogram's for every algorithm discussed.

Final thoughts

This is the point where I notice I'm reaching the five-page limit, and where I stop pontificating about style and add two general reflections.

A moving target

GNOME evolves at a breathtaking pace. Though compatibility has been kept through the major releases—I am glad that what I wrote on GNOME 2.0 is still of some value when developing for 2.10—the “canonical ways” of doing many things have changed and will continue to do so, es­pecially with the latest changes in GTK+ and the foreseeable demise of libgnomeui.

If you write anything larger, such as I did, the problem is to come out with a book that will not at once be outdated. As the a good technical book's development cycle is several months if not more than a year, with today's time-based GNOME releases, it will probably be impossible to get a good book on GNOME onto the market while the version it dis­cusses is still current. This makes me suspect that constantly updated on-line books will be the wave of the future not just for references, but for tutorial-style documentation, too. People like printed manuals, though.

For the user documentation that comes with GNOME components, the problem has largely been solved by freeze discipline. Third-party GNOME user manuals currently, as far as I know, either do not exist or are abysmally bad, and I think the release cycle will rather reinforce this.

So, how hit that moving target at all? There are two solutions:

Prepare everything not directly dependent on the UI or API in advance, then start writing furiously as soon as the new release branches off, and if you're lucky, you'll be done with whatever you wanted to write before it goes gold, and you'll even have time to compensate for changes made between the first pre-versions and the final release.

Do not write books about GNOME. Stick to articles or try some poetry . Or maybe you will be the one to develop the ultimate always-current Wikipedia-like on-line source of GNOME docu­mentation that will be automatically edited into printed form twice a year along with the latest release and sell like fresh bread. This is probably the future, and as soon as it exists, I may try to file a GUADEC paper about how to contribute to it.

Motivation

Last but not least, you will not write anything good without motivation. The question why you write about GNOME might be more interesting than what you are going to write. The niche for printed books seems rather small, considering the so-so sales of most GNOME books, no matter how they were reviewed; chances are you do not write on GNOME to make money as there would be easier ways. Only for best-selling technical books, the royalties divided by the amount of work make a reasonable hourly wage; even writing books that sell comparably well is more like a paid hobby than a real source of income. Magazine articles are hardly ever paid for, and voluntary contributions to on-line documentation never are.

Maybe you see writing as a way to contribute to GNOME without coding, maybe it is your day­time job. Maybe you simply enjoy it? You should. Technical writing may look profoundly inattractive at the surface, but can be fun. Try to make what you are writing more than a text-shaped tool to help users or developers; try to make it something people like to read, but first of all try to make it something you like to write. Writ­ing should not be a chore. Be brilliant. Give your best. There are millions of GNOME users and developers out there and they deserve it.

The Official GNOME 2 Developer's Guide. San Francisco: No Starch Press, 2004. (American translation of: GNOME 2.0. Das Entwickler-Handbuch. Bonn: Galileo Press, 2002.)

I know I have violated this rule writing this paper, but there was just no other way to fit the thing on five pages :)

“GtkTyger! GtkTyger! burning bright / In the GForest of the GNight...”

Michael Kleinhenz

2003-12-06T20:16:47