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.*

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Luminar 1.0.2 - Powerful, adaptive, conf...
Luminar is the new full-featured image editor that adapts to the way you edit photos. Over 300 essential tools to fix, edit, and enhance your photos with comfort. The future of photo editing is here... Read more
WhatRoute 2.0.10 - Geographically trace...
WhatRoute is designed to find the names of all the routers an IP packet passes through on its way from your Mac to a destination host. It also measures the round-trip time from your Mac to the router... Read more
Slack 2.3.3 - Collaborative communicatio...
Slack is a collaborative communication app that simplifies real-time messaging, archiving, and search for modern working teams. Version 2.3.3: Fixed window zoom jumping back-and-forth OS X 10.9... Read more
Lens Blur 1.4.3 - True out-of-focus boke...
Lens Blur transforms your existing photo into true SLR-quality out-of-focus bokeh effect! Everyone needs a gorgeous personalized background for a social profile, blog, Web/UI design, presentation, or... Read more
CleanMyMac 3.6.0 - $39.95
CleanMyMac makes space for the things you love. Sporting a range of ingenious new features, CleanMyMac lets you safely and intelligently scan and clean your entire system, delete large, unused files... Read more
DEVONthink Pro 2.9.8 - Knowledge base, i...
DEVONthink Pro is your essential assistant for today's world, where almost everything is digital. From shopping receipts to important research papers, your life often fills your hard drive in the... Read more
MacFamilyTree 8.1 - Create and explore y...
MacFamilyTree gives genealogy a facelift: modern, interactive, convenient and fast. Explore your family tree and your family history in a way generations of chroniclers before you would have loved.... Read more
HoudahSpot 4.2.7 - Advanced file-search...
HoudahSpot is a powerful file search tool. Use HoudahSpot to locate hard-to-find files and keep frequently used files within reach. HoudahSpot will immediately feel familiar. It works just the way... Read more
TunnelBear 3.0.7 - Subscription-based pr...
TunnelBear is a subscription-based virtual private network (VPN) service and companion app, enabling you to browse the internet privately and securely. Features Browse privately - Secure your data... Read more
Garmin Express 4.5.0.0 - Manage your Gar...
Garmin Express is your essential tool for managing your Garmin devices. Update maps, golf courses and device software. You can even register your device. Update maps Update software Register your... Read more

Latest Forum Discussions

See All

Telltale Games really is working on a Gu...
Telltale Games' next episodic adventure is indeed Guardians of the Galaxy. A document tied to the voice actors strike suggested that the project was in the work, but now we have direct confirmation following an announcement at the Game Awards that... | Read more »
Amateur Surgeon returns to iOS and Andro...
Amateur Surgeon and its two sequels disappeared from the App Store some time and it was sad days for all. But now, just in time for the holidays, the Adult Swim favorite makes its joyous return in the shape of Amateur Surgeon 4, a remake with... | Read more »
The best board games on mobile
Sometimes you need to ditch all of the high speed, high action games in favor of something a little more traditional. If you don't feel like parting ways from your mobile device, though, there are still plenty of ways to get that old-school fix.... | Read more »
The best Facebook Messenger Instant Game...
Facebook's new Instant Games is now here, meaning you can play games with your friends directly via Facebook. It's a fun new way to connect with friends, of course, but it's also proving to be a solid gaming experience in its own right, with a... | Read more »
You can now play game's on Facebook...
Facebook launched its new Instant Games platform in an exciting new attempt to engage its user base. As a result, you can now play a number of different games directly through Facebook Messenger. All of these games run with HTML5, meaning you play... | Read more »
Apollo Justice Ace Attorney (Games)
Apollo Justice Ace Attorney 1.00.00 Device: iOS Universal Category: Games Price: $.99, Version: 1.00.00 (iTunes) Description: Court Is Back In Session Star as rookie defense attorney, Apollo Justice, as he visits crime scenes,... | Read more »
KORG iWAVESTATION (Music)
KORG iWAVESTATION 1.0 Device: iOS Universal Category: Music Price: $19.99, Version: 1.0 (iTunes) Description: A revolutionary new world of sound.The Wave Sequence Synthesizer for iPad - KORG iWAVESTATION | Read more »
Don't Grind Guide: Tips for becomin...
Don’t Grind is a surprising, derpy little one touch game with fun hand-drawn graphics. The goal is simple -- get the high score without being chopped to bits. That can be tough when you’re not used to the game, and that’s compounded by the fact... | Read more »
The top 4 Final Fantasy games on mobile
Final Fantasy XV is out today, and to celebrate we’re breaking down the best Final Fantasy games on mobile. Porting a game to mobile is always tricky business, but many of the early Final Fantasy games have made the transition quite well. Let’s... | Read more »
Swap Sword (Games)
Swap Sword 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: | Read more »

Price Scanner via MacPrices.net

Parallels Toolbox 1.3 for Mac Offers 25 Singl...
Parallels has launched Parallels Toolbox 1.3 for Mac, an upgrade that adds five new utilities to the stand-alone application which was released in August and is available exclusively online at http... Read more
OWC Mercury Elite Pro Dual mini Ultra-Portabl...
OWC has introduced the new OWC Mercury Elite Pro Dual mini, a powerful yet ultra-portable dual-drive RAID solution. The new Mercury Elite Pro Dual mini packs phenomenal performance into a small... Read more
Clearance 13-inch Retina MacBook Pros availab...
B&H Photo has clearance 2015 13″ Retina Apple MacBook Pros available for up to $200 off original MSRP. Shipping is free, and B&H charges NY tax only: - 13″ 2.7GHz/128GB Retina MacBook Pro: $... Read more
Roundup of 2016 13-inch 2.0GHz MacBook Pro sa...
B&H has the non-Touch Bar 13″ MacBook Pros in stock today for $50-$100 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 2.0GHz MacBook Pro Space Gray (MLL42LL/A): $1449 $... Read more
New 13-inch 2.0GHz Space Gray MacBook Pro in...
Adorama has the new 13″ 2.0GHz Space Gray MacBook Pro (non-Touch Bar, MLL42LL/A) in stock for $1499 including a free 3-year AppleCare Protection Plan. Shipping is free, and Adorama charges sales tax... Read more
Finnair Adopts iOS Enterprise iPad Apps from...
Finnair and IBM have announced a first-of-its-kind agreement to utilize iOS enterprise apps from IBM to support the airline’s overall digital transformation. Finnair is focused on Asia-Europe traffic... Read more
Tech21 Launches Evo Go iPhone 7 Case Availabl...
Tech21 has announced the launch of the Evo Go case for Apple iPhone 7 and iPhone 7 Plus, exclusively at T-Mobile. Available online and at participating T-Mobile stores nationwide, Evo Go cases start... Read more
Apple Turns (RED) with More Ways to Join the...
In recognition of World AIDS Day, Apple is offering more ways than ever for customers to join (RED) in its mission to create an AIDS-free generation. Apple is the worlds largest corporate contributor... Read more
Deals on new 15-inch Touch Bar MacBook Pros,...
B&H Photo has new 2016 Apple 15″ Touch Bar MacBook Pro models in stock today with some available for $50 off MSRP, each including free shipping plus NY sales tax only: - 15″ 2.7GHz Touch Bar... Read more
12-inch Retina MacBooks on sale for up to $10...
12-inch Retina MacBooks remain on sale at B&H Photo with models available for up to $100 off MSRP. Shipping is free, and B&H charges NY sales tax only. B&H will also include a free copy... Read more

Jobs Board

*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
US- *Apple* Store Leader Program - Apple (Un...
…Summary Learn and grow as you explore the art of leadership at the Apple Store. You'll master our retail business inside and out through training, hands-on Read more
*Apple* & PC Desktop Support Technician...
Apple & PC Desktop Support Technician job in Dallas TX Introduction: We have immediate job openings for several Desktop Support Technicians with one of our most Read more
*Apple* &Amp Pc Desktop Support Technici...
Apple & PC Desktop Support Technician job in Monroe, CT Introduction: We have immediate job openings for several Desktop Support Technicians with one of our most Read more
*Apple* Retail - Multiple Positions, Fort Wo...
Job Description:SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.