Editors are really valuable, and, the way things are going, undervalued. These are people who are good at process. They think about calendars, schedules, checklists, and get freaked out when schedules slip. Their jobs are to aggregate information, parse it, restructure it, and make sure it meets standards. They are basically QA for language and meaning.

In this paper, I define troubleshooting procedures and briefly sketch out how they are developed. Then I analyze the genre’s underlying architectural structure of diagnosis and resolution, showing both simple and complex configurations of symptoms and solution methods. These configurations are in part constrained by the nature of the technical problem; but they are also the consequence of design decisions. Understanding structure enables us to meaningfully classify the very diverse instances of this genre, reveals key design issues, and is apt to contribute to experimental research insofar as structure is central to many of the most useful research questions we can ask.

In general, numbered section heads use the chapter number as the first digit – but that’s only if you have multiple chapters in a book (1.1, 2.1, 3.1…).

What if you have only one chapter in a book? Do the sections become 1, 2, 3…?

I haven’t been able to find anything discussing this, so if you know of any reference material to back this up, I’d be much obliged!

The Readability Report tool scores your document for readability, cohesion and information density. These scores provide the author with an indication of how well the intended audience will understand the text. The scores use a variety of computational linguistic techniques to determine the reading level of the text.

If you are unfamiliar with the licenses promoted by Creative Commons (CC), you might be taken in by these claims, but they are not true. Lawrence Lessig, cofounder and board member of CC (his day job is Harvard Law School professor and director of the Safra Center for Ethics) explains the situation in this article. In brief, what CC promotes is choice for creators of works (writers, musicians, artists), using more flexible variations on copyright license terms.

Sarah explained the advantages to both the customers and the company of involving readers (users) and discussed some of the techniques that Atlassian has been experimenting with. These include social media (blogs, a forum, and Twitter), a “doc sprint” (an intensive time spent producing documents such as tutorials), encouraging users to update community documentation on a wiki, links to readers’ blogs, and an interactive game that customers can use to help them through the complex installation and configuration of a product.

Anyone who has worked in both a traditional “waterfall” development environment and an agile environment, knows how different they are. If you are comfortable working in one, you may be quite uncomfortable in the other… or you may not, depending on your adaptabiity and tolerance for change. Personally, I thrive on change (or at least variety).

During my time at IBM, I worked on “waterfall” projects, which I found a bit stifling. Now I work with OpenOffice.org, which may or may not be “agile” but certainly is fast-paced in terms of iterative changes to the software. The user documentation team as a group (all volunteers) is always lagging behind the software developers. I suspect a lot of that time lag has to do with our failure to develop processes to handle the workflow, so I’m looking for ways to improve that workflow. Other problems are a lack of enough writers compared to reviewers and editors, and a constanting changing set of volunteers. Engaging volunteers isn’t all that different to engaging readers, and both could help with keeping the documentation up to date and relevant to the users’ needs.

I recommend Sarah Maddox’s blog. Her posts about AODC start here.

Some highlights for me included the talks on structured content and DITA, engaging your readers with the documentation, an overview of Google Apps, user assistance design and implementation for iPhone apps—and the chance to fondle an iPad several weeks before they became available in Australia. I’m now mulling over the possibilities for putting some of what I’ve learned—about both structured authoring and engaging readers—into use at OpenOffice.org.

For details of the speakers and their topics, see speakers page and the agenda pages on the AODC website. The speakers are regulars at AODC as well as WritersUA and similar conferences, with new material every year, presented in an entertaining manner.

I am not going to attempt to summarise the sessions, though I’ll mention some topics of particular interest to me in subsequent blog posts.

This example is taken from one of the OpenOffice.org (OOo) user guides, which was being updated from OOo version 2 to version 3. I show the author’s instructions to the illustrator, the figure the illustrator produced, and my analysis and edit of the figure.

Below is the instruction by the person updating the text of the book to the person updating the illustrations. Notice that the original (version 2) picture was cropped tightly to show only the relevant part of the status bar at the bottom.

The next picture shows the revised illustration, which now shows the version 3 status bar.

The editor’s job is to critically examine this illustration and decide if it needs any improvement. Here are some questions to ask:

• Does this picture show what it is supposed to show?
• Is it clear and easy to see what is being illustrated?
• Should it be cropped and, if so, what should be cut off?

In my opinion, the picture should be cropped to cut out those parts of the status bar that show information that is not about the “current activity or status of the selection” as stated in the text.

Some knowledge of the program is needed at this point, to determine which elements in the status bar are relevant and which are not. The editor could refer to Chapter 1 of the book, which includes a description of the parts of the status bar.

The next picture shows the edited illustration, which has cropped off the right-hand part of the original picture. I think this could be further improved, but for a quick edit it will do.

Comments are welcome.

The revised 2nd edition of Effective Onscreen Editing is now available. The new edition has been extensively revised to include new information, to correct errors in the 1st edition, and to focus on using the techniques with Word 2003, 2007, and 2008. In addition, all Web links have been moved onto my Web site so I can keep them up to date more easily…

My comment: Years ago I wrote a book titled Electronic Editing, followed by a series of books called Taming Microsoft Word. I considered updating the original book, but I’m glad I didn’t take the time. Geoff Hart has written a much better, more complete, and more readable book than I could ever do. I recommend it highly.

Look at each of the examples. How many errors can you spot? How many things should you check to determine if they are correct or wrong? (I missed all of these on a previous, rushed, pass through the document. We definitely need more people reviewing/editing/proofreading/final checking the user guides.)

Example 1a

An editor should check whether the two cross-references to figure numbers are correct. In fact, the figures with those numbers show something entirely different and no figures meeting the description exist anywhere in the document.

The editor should query whether the figures should be added or the cross-references removed. (In this case, the text was copied from another document and the illustration deliberately were not included; but the cross-references remained. In many cases, such cross-references will show up as errors, but for some reason these do not; instead, they point to unrelated figures.)

There are three other errors in this example. The first would be found if the editor used the program to test the statement in the first paragraph. In fact, the correct key combination is Control+Shift+spacebar.

The second error is one of consistency: Shift+Control+minus sign should be Control+Shift+minus sign.

The third error again requires the editor to check the program; Tools > AutoCorrect > Options should be Tools > AutoCorrect Options.

Example 1b

I can find only two errors in this example. First, the caption on Figure 14 should be something like “Setting the measurement unit and default tab stop interval”. Second, the cross-reference to Figure 15 reads “Figure 19″.

Example 1c

This one is a bit more subtle. Can you tell that one of the paragraphs is in a smaller font size than the rest of the text? The paragraph is, in fact, incorrectly tagged with a different paragraph style from the others.

Example 1d

This example contains two subtle errors. The last paragraph repeats the third paragraph but is phrased slightly differently. The fourth paragraph contains a reference to a chapter in another book, so it should read “See Chapter 7 (Working with Styles) in the Writer Guide for…” The editor should have the tables of contents of the various books.