TweetFollow Us on Twitter

December 96 - The Veteran Neophyte: Confessions of a Veteran Technical Writer

The Veteran Neophyte:
Confessions of a Veteran Technical Writer

Tim Monroe

I've been a technical writer long enough to have learned a few trade secrets, if you will, that guide me in my daily work and (sometimes, I hope) help me to do it a little better. Whether you're reading manuals for content, working with technical writers to document your own software, or even writing documentation yourself, understanding these secrets might be of value to you. I've long had it in mind to write a book about these and other topics, sort of a general discourse on technical thought and how to do it better. Until I actually write that book, however, the following confessions will have to do.

These confessions should help you understand some of the tasks that some technical writers typically perform and some of the conflicting forces that shape final documents. (Note the profusion of the word some: your mileage may vary.) For fun -- and for another reason that I won't tell you yet -- each confession is introduced by an appropriate palindrome (a word or phrase that reads the same forward and backward).


MADAM, I'M ADAM

As you probably know, Adam was given the task of naming the plants and animals. In a way, Adam was the first technical writer, for an important part of technical writing is to systematize and regularize the nomenclature used in some specific area of interest. It's rare for the engineers developing software to pay very close attention to naming issues. Indeed, the rule is quite the contrary: more often than not, the technical specifications written by engineers are rife with conflicting, inconsistent vocabulary. It nearly always falls to the writers and their editors to clean things up and present the technology using clear, regular, and concise terminology.

There's a moderately foolproof way to discern which writers take this job seriously and which do not: just look at a document's glossary. For my money, every draft of every technical document should include a robust glossary that defines the special terms and concepts used in the document. You simply cannot write any significant part of a technical document without grappling with naming issues. A working, growing glossary is the writer's proof that he or she is actively thinking about these issues and is developing a preferred vocabulary to describe the technology being documented.

Don't be misled by the fact that the glossary is usually one of the last items in a book: as I see it, the glossary ought to be written concurrently with the book, not after it. (The index is another issue altogether: a book cannot be properly indexed until it's nearing completion. Trying to do an index while a document is still changing usually results in tremendous frustration.)


SUE US, ONO, SUE US!

At some point in the distant past, Apple Computer reached an agreement with the Beatle's record company, Apple Records, that allowed Apple Computer to use the name "Apple" so long as it did not engage in certain markets, such as music recording. At some later point in the distant past, Apple Records sued Apple Computer, alleging certain violations of that agreement. Suddenly, the lawyers at Apple Computer were intensely interested in the sound and music capabilities of the Macintosh hardware and system software.

At that moment, I happened to be finishing up the Sound Manager chapter of Inside Macintosh Volume VI. Apple's lawyers decided that a number of API elements smacked too much of music and needed therefore to be changed. For instance, it was thought that since music is composed of individual notes, the word note should not occur anywhere in the documentation in any sound-related sense. As a result, what was hitherto known as the noteCmd constant was changed to freqDurationCmd (the idea being that playing a note is just playing a frequency for a specific duration). The legal department demanded a number of other changes, which led to some last-minute rewriting and reindexing as the book neared publication. And, of course, the engineers had to issue new header files to reflect the new names.

I don't imagine that Yoko Ono and other Apple Records executives have spent much time reading Inside Macintosh, so I doubt that my efforts were all that critical. Nonetheless, I learned my lesson. I confess: I've come to appreciate the difficult job done by the Apple legal department. I now pay close attention to the lists of trademarks distributed by the editors in our department, and I'm constantly on the lookout for API elements that might step on someone's copyrighted toes.


YAWN WAY

Let's face it: technical writing isn't creative writing. It's not designed to enthrall, just to educate and to serve as a useful reference during your daily work. To be useful, a technical document has to be complete. It also has to be consistent in style and vocabulary with other similar documents -- in my case, with other Inside Macintosh books. ("No manual is an island.") Providing documents that are both complete and consistent usually means following a pretty strict set of rules and guidelines governing the style, organization, and content of the document. It can get to be drudgery, sometimes. Yawn.

On the upside, having rules and other established methods to follow can be incredibly liberating. These shackles free you from constantly having to rethink major issues about a document you're writing. Once you figure out what goes where, in a general sense, you almost don't need to think any more. You just take the API elements that need documenting, plug them into the correct paragraph formats, and fill in the appropriate information. It can get to be too easy, sometimes. Yawn.

Following rules, though laudable, is not without its own problems. The requirement that every constant in an API be precisely described can result in some pretty silly stuff. For instance, page 2-33 in the book Inside Macintosh: PowerPC System Software takes the trouble to inform us that the constant kRegisterD0 stands for the register D0. Did anyone have any doubt about that? It can get to be too dumb, sometimes. Yawn.

Have we reached the stage where the API is self-documenting, where just the names of functions and constants give us all the information we need to use them effectively? I don't think so. It's just plain dangerous to start having writers decide what's too obvious to need description and what isn't. In my mind, every element of an API should be fully documented, even if we end up with a few odd cases where there really is nothing more to say. Remember, degenerate cases like these are a direct result of systematically applying rules and established methods. They're a clear signal that the writer is doing things exactly right.


IF I HAD A HI-FI...

...I'd play it real loud, and I'd turn the bass way up. That's the only way to play reggae music, which is what I listen to mostly. My taste in music is quirky, but that's a problem of mine generally. I confess: I adopt methods that help me get my work done, even if those methods are quirky. I revel in quirks, because they often pay off.

So I'll confess another quirk of mine: I write my documents backward. For each chapter, I start at the end and write the summary first. This actually makes good sense, since what I'm documenting is usually an API, as defined by a header file. The summary is really just an improved header file. It's improved in part because it attempts to impart more order and consistency than you'll find in a typical header file. It's important to keep in mind that header files are designed for compilers, not for humans. There's lots of junk in these files that has absolutely no meaning to a programmer. The summary provides an ordered distillation of the header file to its key components.

Once I've written my summary, I have a good head start on the reference section. That's because the summary already contains intelligent groupings and orderings for the basic language elements. To write the reference section, I simply need to "fill in the blanks" provided by the summary: Each constant needs a precise definition. Each data structure needs to have its use explained, and each of its fields must be fully described. Each function has parameters that need describing, and it probably returns a value that must be described.

Only when I've finished the summary and reference sections do I even think about the first parts of the chapter, the About and Using sections. At that point, I need to turn down the music and do some real thinking.


GOD? DOG?

Good technical writing is far too often simply taken for granted. Partly that's an occupational hazard: when it's done right, good documentation is unobtrusive: it purposely doesn't try to be cheeky or clever. More important, good technical writing is unobtrusive because it doesn't jar the reader with confusing organization, sloppy diction, or bad transitions from one topic to the next. Its job is to conform to established styles and norms, and to present information as straightforwardly and clearly as possible. Nonetheless, it bugs me that I've never seen a single review of any Inside Macintosh book. Even magazines that are geared specifically at Macintosh programmers, like MacTech Magazine, never actually bother to review these important books. Third-party books get plenty of discussion, but not the primary documents they all draw on.

I see some other signs that technical writing is taken for granted -- like product managers who try to bring a writer onto a project two weeks before the CDs are to be pressed, and engineers who would rather have a root canal than review the chapter describing the technology they've slaved over for months or perhaps years. What these people are missing is that good documentation can add a considerable amount of value to an engineering product. Documentation is the first and most important bridge between the engineers and the developers using their technology. If the documentation paints a compelling reason to adopt the technology and facilitates that adoption by providing useful sample code and complete descriptions of the API, the writer is a god. Occasionally, the "wow" factor emerges: documentation that is so compelling that it opens your eyes wider and makes your fingers itchy for some coding.

The flip side of the "wow" factor is the "dud" factor: documentation that is so patently bad it almost single-handedly ensures limited adoption for the technology it describes. I've seen some really good technologies languish for years, for no other discernible reason than that they're tied to some really lousy documentation. The best software technology and the best API cannot survive a mauling by a dog technical writer.


"OTTO," MY MOTTO

Palindromes delight us because they call attention to a fairly rare phenomenon: a sequence of letters that is meaningful and that reads the same forward or backward. Language wasn't designed to be palindromic, and there is no cognitive benefit -- no additional information -- in a particular phrase or sentence that happens to be reversible. It's usually a serendipitous accident that some long sentence should be palindromic.

At their best, palindromes tweak our sense of order. As I've suggested above, order itself is deceptive. The linear order of presentation that you find in technical documentation like Inside Macintosh reflects, in all likelihood, neither the order in which the document was written nor the order in which you're most likely to access the information in it. In fact, the principle according to which most good documentation is organized is a complex hybrid of at least two ordering schemes.

On one hand, there is a principle governing how you should be able to learn from a document: you should be able to pick up a document (a book or a chapter) and read it from start to finish with good comprehension. Concepts should be explained in a clear, cumulative order, and tasks should be explained in the order they need to be performed. I like to call this a pedagogically linear path through the document. The good writer progressively reveals more and more of the technology as he or she goes along. This is the main principle that governs the opening sections of an Inside Macintosh chapter (the About and Using sections).

On the other hand, there is a principle governing how you should be able to find information in a document. Technical documentation is, above all, a type of reference material. You're constantly jumping into the middle of a chapter to find the meaning of a constant, or the type of a parameter to a function, or some similar piece of information. It's common to call this random access to the information, but I prefer to avoid that term, since it might suggest that the information itself is ordered randomly. In my opinion, pure reference material (such as that found in the reference and summary sections of Inside Mac chapters) must be organized hierarchically, where the items are intelligently divided into groups, which are themselves further subdivided into groups, until every item can be reached by a meaningful path from the top of the hierarchy. I like to call this the hierarchically linear path to the information. (For reference material, the main competitor to a hierarchical organization is the standard alphabetical organization, which some of you might prefer. Personally, I like to have things grouped by functional similarity, not ordered -- "one darn thing after another" -- by name.)

The pedagogical order and the hierarchical order are clearly different ways of organizing information. If you follow a pedagogical path, you might not get where you want to go very quickly, but you'll get a complete picture of the terrain as you pass through it. If you follow a hierarchical path, you can get where you want to go pretty quickly, but only if you already know where you're going. So, to use the hierarchical path, you must already have traveled the pedagogical path. These two ordering principles depend on each other and should never be separated.

As you can see, order dominates my mind, at least when I'm writing technical documentation. That's why my motto is a palindrome. Attention to order -- and clearly understanding exactly what kind of order is relevant to the task at hand -- is the foundation of all good technical writing.


    RELATED READING

    • Go Hang a Salami! I'm a Lasagna Hog! and Other Palindromes by Jon Agee (Farrar, Straus, and Giroux, 1991).

    • Inside Macintosh by Apple Computer, Inc. (Addison-Wesley, 1992 and following).


TIM MONROE (monroe@apple.com) recently became a Senior Software Engineer in the QuickTime VR group at Apple. He already misses the smart rams and star rats in the technical writing group at Apple Developer Relations. In his spare time, he likes to stack cats and drive his race car to the local llama mall.*

Thanks to Dave Bice, Sharon Everson, and Antonio Padial for reviewing this column.*

 
AAPL
$96.13
Apple Inc.
+0.53
MSFT
$42.86
Microsoft Corpora
-0.30
GOOG
$566.07
Google Inc.
-5.53

MacTech Search:
Community Search:

Software Updates via MacUpdate

Data Rescue 3.2.4 - Recover lost data on...
Data Rescue is a robust and reliable hard-drive recovery solution for your Mac. Recover lost or deleted files, mount corrupted drives, and more -- Data Rescue offers complete relief from crippling... Read more
Adobe Lightroom 5.6 - Import, develop, a...
Adobe Lightroom software helps you bring out the best in your photographs, whether you're perfecting one image, searching for ten, processing hundreds, or organizing thousands. Create incredible... Read more
OneNote 15.2 - Free digital notebook fro...
OneNote is your very own digital notebook. With OneNote, you can capture that flash of genius, that moment of inspiration, or that list of errands that’s too important to forget. Whether you’re at... Read more
iStat Menus 4.22 - Monitor your system r...
iStat Menus lets you monitor your system right from the menubar. Included are 8 menu extras that let you monitor every aspect of your system. Some features: CPU -- Monitor cpu usage. 7 display... Read more
Ember 1.8 - Versatile digital scrapbook....
Ember (formerly LittleSnapper) is your digital scrapbook of things that inspire you: websites, photos, apps or other things. Just drag in images that you want to keep, organize them into relevant... Read more
OmniPlan 2.3.6 - Robust project manageme...
With OmniPlan, you can create logical, manageable project plans with Gantt charts, schedules, summaries, milestones, and critical paths. Break down the tasks needed to make your project a success,... Read more
Command-C 1.1.1 - Clipboard sharing tool...
Command-C is a revolutionary app which makes easy to share your clipboard between iOS and OS X using your local WiFi network, even if the app is not currently opened. Copy anything (text, pictures,... Read more
Knock 1.1.7 - Unlock your Mac by knockin...
Knock is a faster, safer way to sign in. You keep your iPhone with you all the time. Now you can use it as a password. You never have to open the app -- just knock on your phone twice, even when it's... Read more
Mellel 3.3.6 - Powerful word processor w...
Mellel is the leading word processor for OS X and has been widely considered the industry standard since its inception. Mellel focuses on writers and scholars for technical writing and multilingual... Read more
LibreOffice 4.3.0.4 - Free Open Source o...
LibreOffice is an office suite (word processor, spreadsheet, presentations, drawing tool) compatible with other major office suites. The Document Foundation is coordinating development and... Read more

Latest Forum Discussions

See All

Bio Inc. is $0.99 for the Weekend, Recei...
Bio Inc. is $0.99 for the Weekend, Receives Small Update Posted by Ellis Spice on August 1st, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Happy 7th Birthday Readdle! Thank You fo...
Happy 7th Birthday Readdle! | Read more »
Sharknado: The Video Game Review
Sharknado: The Video Game Review By Lee Hamlet on August 1st, 2014 Our Rating: :: SHARKNA-DON'TUniversal App - Designed for iPhone and iPad Sharknado: The Video Game brings the craziness of the movies to iOS, though it quickly... | Read more »
Clima (Weather)
Clima 1.0 Device: iOS iPhone Category: Weather Price: $.99, Version: 1.0 (iTunes) Description: Clima show you all weather information, just beautifully simple. A series of color bars can tell you at a glance exactly current... | Read more »
Sticky Soccer Review
Sticky Soccer Review By Andrew Fisher on August 1st, 2014 Our Rating: :: STICK THIS GAMEUniversal App - Designed for iPhone and iPad Sticky Soccer puts too much emphasis on the ‘sticky’ and not enough on the ‘Soccer’ or ‘Fun’.   | Read more »
Graphics-less Apocalyptic Adventure A Da...
Graphics-less Apocalyptic Adventure A Dark Room Goes Free for a Limited Time Posted by Rob Rich on August 1st, 2014 [ permalink ] | Read more »
Fraud Tycoon Review
Fraud Tycoon Review By Rob Thomas on August 1st, 2014 Our Rating: :: UNHEALTHY CREDITUniversal App - Designed for iPhone and iPad Fraud Tycoon is a half-baked, messy, promotional tie-in that does their sponsor no favors whatsoever... | Read more »
Guardians of the Galaxy: The Universal W...
Guardians of the Galaxy: The Universal Weapon is on Sale for the Weekend Posted by Rob Rich on August 1st, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Mister Beam Review
Mister Beam Review By Jordan Minor on August 1st, 2014 Our Rating: :: ILLUMINATINGUniversal App - Designed for iPhone and iPad Mister Beam’s puzzles are great. But its platforming? Not so much.   | Read more »
Hook Some More Fun With MapHook’s New Up...
Hook Some More Fun With MapHook’s New Update Posted by Jessica Fisher on August 1st, 2014 [ permalink ] iPhone App - Designed for the iPhone, compatible with the iPad | Read more »

Price Scanner via MacPrices.net

13-inch MacBook Airs on sale for $100 off MSR...
B&H Photo has the new 2014 13″ MacBook Airs on sale $100 off MSRP. Shipping is free, and B&H charges NY sales tax only. They also include free copies of Parallels Desktop and LoJack for... Read more
16GB iPad Air on sale for $399, save $100
Best Buy is offering the 16GB WiFi iPad Air for $399.99 on their online store for a limited time. Their price is $100 off MSRP. Choose free shipping or free store pickup (if available). Price is for... Read more
All Over For Tablets Or Just A Maturing, Evol...
CNN’s David Goldman weighs in on tablet sector doom and gloom, asking rhetorically: “Is this the beginning of the end for the tablet?” Answering that, he contends that hysteria and panic are... Read more
Letterspace 1.0.1 – New Free iOS Text Editor...
Bangkok, Thailand based independent developer Sittipon Simasanti has released Letterspace, a new text editor for iPhone, iPad, and iPod touch devices. Letterspace is a note taking app with an... Read more
Save up to $130 on an iPad mini with Apple re...
The Apple Store has Certified Refurbished 2nd generation iPad minis with Retina Displays available for up to $130 off the cost of new models, starting at $339. Apple’s one-year warranty is included... Read more
iPad Cannibalization Threat “Overblown”
Seeking Alpha’s Kevin Greenhalgh observes that while many commentators think Apple’s forthcoming 5.5-inch panel iPhone 6 will cannibalize iPad sales, in his estimation, these concerns are being... Read more
Primate Labs Releases July 2014 MacBook Pro P...
Primate Labs’ John Poole has posted Geekbench 3 results for most of the new MacBook Pro models that Apple released on Tuesday. Poole observes that overall performance improvements for the new MacBook... Read more
Apple Re-Releases Bugfixed MacBook Air EFI Fi...
Apple has posted a bugfixed version EFI Firmware Update 2.9 a for MacBook Air (Mid 2011) models. The update addresses an issue where systems may take longer to wake from sleep than expected, and... Read more
Save $50 on the 2.5GHz Mac mini, plus free sh...
B&H Photo has the 2.5GHz Mac mini on sale for $549.99 including free shipping. That’s $50 off MSRP, and B&H will also include a free copy of Parallels Desktop software. NY sales tax only. Read more
Save up to $140 on an iPad Air with Apple ref...
Apple is offering Certified Refurbished iPad Airs for up to $140 off MSRP. Apple’s one-year warranty is included with each model, and shipping is free. Stock tends to come and go with some of these... Read more

Jobs Board

Position Opening at *Apple* - Apple (United...
**Job Summary** The Apple Store is a retail environment like no other - uniquely focused on delivering amazing customer experiences. As an Expert, you introduce people Read more
Position Opening at *Apple* - Apple (United...
**Job Summary** At the Apple Store, you connect business professionals and entrepreneurs with the tools they need in order to put Apple solutions to work in their Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Sr. Product Leader, *Apple* Store Apps - Ap...
**Job Summary** Imagine what you could do here. At Apple , great ideas have a way of becoming great products, services, and customer experiences very quickly. Bring Read more
Sr Software Lead Engineer, *Apple* Online S...
Sr Software Lead Engineer, Apple Online Store Publishing Systems Keywords: Company: Apple Job Code: E3PCAK8MgYYkw Location (City or ZIP): Santa Clara Status: Full Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.