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
$113.99
Apple Inc.
+1.98
MSFT
$47.88
Microsoft Corpora
-0.26
GOOG
$534.03
Google Inc.
+5.26

MacTech Search:
Community Search:

Software Updates via MacUpdate

Google Drive 1.18.7821.2489 - File backu...
Google Drive is a place where you can create, share, collaborate, and keep all of your stuff. Whether you're working with a friend on a joint research project, planning a wedding with your fiancé, or... Read more
Eye Candy 7.1.0.1203 - 30 professional P...
Eye Candy renders realistic effects that are difficult or impossible to achieve in Photoshop alone, such as Fire, Chrome, and the new Lightning. Effects like Animal Fur, Smoke, and Reptile Skin are... Read more
Airfoil 4.8.12 - Send audio from any app...
Airfoil allows you to send any audio to AirPort Express units, Apple TVs, and even other Macs and PCs, all in sync! It's your audio - everywhere. With Airfoil you can take audio from any... Read more
MegaSeg 5.9.4 - Professional MP3 DJ appl...
MegaSeg is a complete solution for pro audio/video DJ mixing, radio automation, and music scheduling with rock-solid performance and an easy-to-use design. Mix with visual waveforms and Magic... Read more
Parallels Desktop 10.1.2 - Run Windows a...
Parallels Desktop is simply the world's bestselling, top-rated, and most trusted solution for running Windows applications on your Mac. With Parallels Desktop for Mac, you can seamlessly run both... Read more
GarageSale 6.9.1 - Create outstanding eB...
GarageSale is a slick, full-featured client application for the eBay online auction system. Create and manage your auctions with ease. With GarageSale, you can create, edit, track, and manage... Read more
Quicksilver 1.2.2 - Application launcher...
Quicksilver is a light, fast and free Mac application that gives you the power to control your Mac with keystrokes alone. Quicksilver allows you to find what you need quickly and easily, then act... Read more
Mac DVDRipper Pro 5.0.1 - Copy, backup,...
Mac DVDRipper Pro is the DVD backup solution that lets you protect your DVDs from scratches, save your batteries by reading your movies from your hard disk, manage your collection with just a few... Read more
ClamXav 2.7 - Free virus checker, based...
ClamXav is a free virus checker for OS X. It uses the tried, tested, and very popular ClamAV open source antivirus engine as a back end. I hope you like and use ClamXav a lot and that it helps keep... Read more
FoldersSynchronizer 4.2 - Synchronize or...
FoldersSynchronizer is a popular and useful utility that synchronizes and backs-up files, folders, disks and boot disks. On each session you can apply special options like Timers, Multiple Folders,... Read more

Latest Forum Discussions

See All

Forget the Gloves – It’s a Cage Match in...
Forget the Gloves – It’s a Cage Match in Real Boxing’s Underground Update Posted by Jessica Fisher on December 23rd, 2014 [ permalink ] | Read more »
Who Wore it Best? Best of 2014
It’s the end of the year, so it’s time for some arbitrary internet awards! In this wrap-up episode of Who Wore it Best? we present our winners for the best, worst, and flat-out weirdest cloned games that graced the App Store in 2014. [ Who... | Read more »
Now You Can Explore Mayan Temples in Ass...
Now You Can Explore Mayan Temples in Assassin’s Creed Pirates’ Newest Update Posted by Jessica Fisher on December 23rd, 2014 [ permalink ] | Read more »
Soft Design aims to do free-to-play righ...
They say a team is only as big as its fans and that’s also certainly the case with video games, judging from the sales certain AAA ‘heavyweights’ get year-after-year. Soft Design took that principle as a core design philosophy and worked closely... | Read more »
Bogga Christmas Tree
Bogga Christmas Tree By Amy Solomon on December 23rd, 2014 Our Rating: Universal App - Designed for iPhone and iPad Bogga Christmas Tree allows young children to trim a tree, any time or place.   | Read more »
Opera Coast 4.0 Launches on iOS with 4 N...
Opera Coast 4.0 Launches on iOS with 4 New Features Posted by Jessica Fisher on December 23rd, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Cricket Kids: Christmas Presents
Cricket Kids: Christmas Presents By Amy Solomon on December 23rd, 2014 Our Rating: Universal App - Designed for iPhone and iPad Cricket Kids: Christmas Presents allows children to play with digital toys opened for the Christmas... | Read more »
Lara Croft & Tomb Raider Mobile Bund...
Lara Croft & Tomb Raider Mobile Bundle – Only $4.99 Posted by Jessica Fisher on December 23rd, 2014 [ permalink ] Lara Croft is coming to you in | Read more »
SimCity BuildIt Review
SimCity BuildIt Review By Nadia Oxford on December 23rd, 2014 Our Rating: :: BUILDING AN OK TOMORROWUniversal App - Designed for iPhone and iPad SimCity BuildIt is a competent city-building game, but its free-to-play trappings are... | Read more »
SimCity Buildit – Tips, Tricks, and Stra...
Hello, Budding Mayors Want to know what we made of all this upgrading and inevitable waiting? Check out our SimCity BuildIt review! SimCity BuildIt is a city-building game from EA. Your job as mayor is to build houses for people to live in, industry... | Read more »

Price Scanner via MacPrices.net

Sony Fixing To Launch Large-Screen Android Ta...
Digitimes’ Aaron Lee and Joseph Tsai report that Sony, which last February exited the laptop computer market with the sale of its VIAO PC-making unit to a group of JApanese investors, is now expected... Read more
After Christmas sale: 13-inch Retina MacBook...
B&H Photo has new 13″ MacBook Pros on sale for up to $150 off MSRP as part of their Holiday pricing. Shipping is free, and B&H charges NY sales tax only: - 13″ 2.5GHz MacBook Pro: $1043 save... Read more
After Christmas sale: 15-inch Retina MacBook...
Adorama has 15″ Retina MacBook Pros on sale for up to $150 off MSRP. Shipping is free, and Adorama charges NY & NJ sales tax only: - 15″ 2.2GHz Retina MacBook Pro: $1899 save $100 - 15″ 2.5GHz... Read more
After Christmas sale: MacBook Airs for up to...
B&H Photo has 2014 MacBook Airs on sale for up to $120 off MSRP, for a limited time, for the Thanksgiving/Christmas Holiday shopping season. Shipping is free, and B&H charges NY sales tax... Read more
Apple now offering Certified Refurbished Mac...
The Apple Store is now offering Apple Certified Refurbished 2014 Mac minis, with models available starting at $419. Apple’s one-year warranty is included with each mini, and shipping is free: - 1.... Read more
Will Apple Build An A-series ARM Processor Po...
In computer terms, it’s been a very long time since the MacBook Air had a major redesign. More than four years have elapsed since Apple recast what had originally been more a pricy boutique device... Read more
iPhone 6s mini With Four-Inch Screen Rumored...
The Times of India’s Komal Mohan, citing a story in The Electronic Times of Taiwan, says that unnamed upstream supply chain sources report that Apple is gearing up to launch a new 4-inch screen... Read more
What’s The Current Value Of Your iOS Apps?
Basel, Switzerland based ConIT AG has announced AppZapp Notify and its free PC and Mac tool available for download. What is the present value of all my downloaded Apps? With AppZapp Notify, for the... Read more
PhatWare Releases WritePad Pro Advanced iOS W...
PhatWare Corporation has announced immediate availability of WritePad Pro 2.0, its advanced word processing, note-taking, and document management app which also takes full advantage of PhatWare’s... Read more
Last minute gift idea: Send an Apple Store Gi...
Send an Apple Store Gift Card by email this season, perhaps as a last minute Christmas gift. According to Apple, “Apple Store Gift Cards can be used to purchase Apple hardware and accessories at any... Read more

Jobs Board

Position Opening at *Apple* - Apple (United...
…Summary** As a Specialist, you help create the energy and excitement around Apple products, providing the right solutions and getting products into customers' hands. You Read more
Position Opening at *Apple* - Apple (United...
**Job Summary** Being a Business Manager at an Apple Store means you're the catalyst for businesses to discover and leverage the power, ease, and flexibility of Apple Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
Senior Event Manager, *Apple* Retail Market...
…This senior level position is responsible for leading and imagining the Apple Retail Team's global event strategy. Delivering an overarching brand story; in-store, Read more
*Apple* Store Leader Program (US) - Apple, I...
…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 experience, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.