The Fedora Desktop User Guide needs some editing

Aimed at new users, the Fedora Project’s Fedora Desktop User Guide (FDUG) attempts to address some worthwhile questions: What does its audience want to do? What does the audience need to know to accomplish those tasks? What explanations and layout will help them absorb the information they need as easily and as quickly as possible? FDUG does a reasonable job of anticipating audience need, covering topics from logging in and basic desktop features to descriptions of setting up mail and managing photos and sharing directories. However, its presentation of information fails to answer the other questions implicit in technical writing, and suffers in both text and design from a lack of consistency.

Some sections of the FDUG meet the highest standards of technical writing. The “Managing Photos” section begins with a brief overview of using digital cameras with Fedora, then gives a succinct numbered list of steps for connecting a camera to a computer, avoiding the needless use of the word “mount” and carefully considering various options and describing how to organize photos. The “Sharing Your Desktop” section is even more succinct and tightly structured.

Unfortunately, these sections are the exception in FDUG, not the rule. The information in the “Office Tools” and “Playing Multimedia” sections are nothing more than lists of applications, with only the briefest descriptions of them. Full descriptions of the software mentioned would probably be out of place, yet to be useful to new users, the sections could at least mention some common problems new users have with the software, such as how to set up multiple footers and headers in OpenOffice.org Writer. At the very least, some links to more concrete information would be useful — general links with only the most general indication of what users will find are hardly enough.

Other sections are midway between these extremes, but struggle with other problems. One especially common problem throughout is the lack of any sense of when jargon needs to be explained and used. For instance, the writers of the “Using Media” section remember to provide a brief explanation of Nautilus, but forget to define “mounted.” Conversely, those responsible for the “Logging In” section make such an effort to avoid jargon that, instead of naming the login screen, they say “any user can now login when the display looks similar to the picture below,” with no mention of when that similarity might occur, and they describe the username field as “the horizontal field containing a blinking black bar,” even though it is clearly labeled in GDM. Surely, between these two extremes there is a moderate approach that minimizes jargon but carefully explains the terms that are used. New users need some jargon so that they can get help from the more experienced.

Another balance which the FDUG only intermittently achieves is that between the focus on immediate tasks and the background information that would allow new users to understand more about the operating system and software tools. Too many sections launch into a description of various tasks without giving any background that might explain why users would want to do a task, or offer too little information about the operating system for users to understand what they are doing.

Moreover, nowhere does the FDUG explain that most of the actions they describe take place within a specific user account with a home directory under /home, or that mounted drives are not lettered as in Windows. In the same way, while “Accessing the Web” focuses on Firefox, it does not mention alternative browsers, or, in mentioning extensions, that users can install them for themselves by selecting Tools -> Add-Ons from the menu. Some basic topics, such as file management and keyboard shortcuts, which deserve sections to themselves, are hardly mentioned, while KDE is ignored altogether, even as a possibility that users might want to explore on their own. Admittedly, newcomers should not face too many options right away, but choice is a major feature of any distribution. By not at least sketching out the most basic alternatives, FDUG fails to provide for those new users who want more than the basics.

Because FDUG is formatted in HTML, its layout options are limited. However, the guide often fails to make the best use of the few options available. At times, especially in the “Logging In” section, the positioning of notes and warnings seems random and unconnected with the text before or after. In much the same way, some terms are italicized, but not all, and hyperlinks are rarely used to provide more information. The layout is also inconsistent from section to section, with bullet lists used in some sections and tables in others. The impression is that the sections of the guides were written separately, with no effort to maintain consistency in usage and layout throughout.

Such criticisms may seem harsh for such an obviously well-meaning effort. However, documentation for beginners is still a rarity in GNU/Linux, so the subject is worth taking seriously. With a little more effort, FDUG could be a useful addition to this documentation, not just for Fedora, but, with a few changes of screenshots, for any GNOME-based distribution. However, in order to reach this potential, in the next draft FDUG’s writers need to do a better job of imaginatively projecting themselves into new users’ minds, and must establish some standards for writing and layout.

Bruce Byfield is a computer journalist who writes regularly for NewsForge, Linux.com, and IT Manager’s Journal. He worked as a technical writer for several years, and continues to have a special interest in presenting technical information to inexperienced users.