TweetFollow Us on Twitter

March 93 - Editor's Note

EDITOR'S NOTE

CAROLINE ROSE

Dear Readers,

In May of last year, I schmoozed with a lot of developers at Apple's Worldwide Developer's Conference, and one of the subjects that came up was documentation. I expressed my ideas on this subject somewhat hesitantly, because I thought the truths I was spouting were all pretty obvious, but I was surprised to find that several developers seemed enlightened by them and even suggested this as a topic for a develop  editorial. So here goes.

But first, some motivation. If you're one of those developers who think no one reads manuals anyway, has it occurred to you that this might be a self-fulfilling prophecy? If manuals were better, maybe people would read them. Also, customers who do  never read the manual will never learn the full power of your product (probably not every  feature is self-explanatory) and will be that much quicker to move on when someone shows them the great things a rival product can do. More likely, people glance at the manual to get started and then thumb through it later when they want to explore certain features.

Also keep in mind that a shoddy manual will be seen as a reflection of the product as a whole: "If this is the best they could do on the manual, how good can their software be?" Don't fool yourself that only writers or editors will criticize a poorly done manual; any reader who has trouble learning from it will complain, and not just to themselves. While there are times when consistency may be the hobgoblin of small minds, it's often the case that inconsistent presentation or terminology will confuse readers and have them throwing your manual down in disgust and thinking your product is more complicated than it really is. And people who do know things like the difference between "its" and "it's" will wonder how well you debugged your code if you couldn't find mistakes like this in your manual. Basically, you won't look like a class act.

I'll state the following points with user documentation in mind, though most of them also apply to technical documentation for developers. Some points may be useful only to small companies, but there should be something here for everyone.

  • Get a technical writer to write your documentation. Don't do it yourself -- and try to talk the CEO or VP of Marketing out of doing it. Contrary to many people's opinions, writing a manual is not something any smart person can do; it's a skill like any other. Most likely you are no more qualified to write the documentation than a writer is qualified to write your code.
  • Look over a relevant writing sample from your prospective writer. Awards, certificates, and years of experience go only so far: nothing will tell you whether you'll get a good manual as much as looking at past work. Ask how the material for the sample was gathered, who else contributed to it, and how heavily it was edited.
  • Get the writer started early in the process -- long before the feature set is frozen. Writers provide a valuable perspective of your product, not unlike that of product management. They'll help with the design of the product, telling you what features don't fit in with other ones and pointing out loopholes, inconsistencies, and other Bad Things. And they're typically excellent bug finders.
  • Have the documentation edited by an editor. Unless they also happen to be editors, writers need their work checked like anyone else -- and an electronic spelling or grammar check (while a good start) isn't enough.
  • Test the result on users, after your product ships if not sooner (you can revise the documentation for the next printing). And don't be defensive: if only one out of ten "testers" turns up a particular problem, it may mean that 10% of your user base will have the same problem. Judge no misunderstanding as stupid; they're all valid, no matter how much you may disagree with them.

I could go on forever, but that's enough for now. Please make my day and let me know if you got anything of value out of this. Or criticize it if you like; I can use the practice in not being defensive.

Caroline Rose Editor


CAROLINE ROSE (AppleLink CROSE) has been writing and editing software documentation since many of you were rug rats. She began at a timesharing company, joined Apple in 1982 to write Inside Macintosh , and helped get NeXT off the ground in 1986. Back at Apple now, she has seven issues of develop  under her belt and is still having a wonderful time. A transplanted New Yorker, Caroline visited the East Coast last October in time to see the leaves turn colors. She enjoyed doing the theater and museum thing in Manhattan and hitting some incredible restaurants and nightclubs -- not to mention a deli whose smoked mozarella is the best this side of Naples. But the highlight was her visit to a friend's farm in Connecticut (sheep feeding beats sheet feeding any day!). Walking to an apple orchard and tasting fresh sweet cider was sheer rural bliss.*

SUBSCRIPTION INFORMATION To subscribe to develop , use the subscription card in the back of this issue. Please address all subscription-related inquiries to develop,  Apple Computer, Inc., P.O. Box 531, Mt. Morris, IL 61054 (or AppleLink DEV.SUBS). *

BACK ISSUESFor information about back issues of develop  and how to obtain them, see the last page of this issue. Back issues are also on the Developer CD Series  disc.*

 
AAPL
$100.91
Apple Inc.
+0.38
MSFT
$44.97
Microsoft Corpora
-0.36
GOOG
$584.63
Google Inc.
-2.23

MacTech Search:
Community Search:

Software Updates via MacUpdate

Tidy Up 3.0.15.0 - Find duplicate files...
Tidy Up is a complete duplicate finder and disk-tidiness utility. With Tidy Up you can search for duplicate files and packages by the owner application, content, type, creator, extension, time... Read more
Parallels Desktop 10.0 - Run Windows app...
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
Apple Final Cut Pro X 10.1.3 - Professio...
Apple Final Cut Pro X is a professional video editing solution.Completely redesigned from the ground up, Final Cut Pro adds extraordinary speed, quality, and flexibility to every part of the post-... Read more
Apple Compressor 4.1.3 - Adds power and...
Compressor adds power and flexibility to Final Cut Pro X export. Customize output settings, work faster with distributed encoding, and tap into a comprehensive set of delivery features. Powerful... Read more
Chromium 36.0.1985.143 - Fast and stable...
Chromium is an open-source browser project that aims to build a safer, faster, and more stable way for all Internet users to experience the web. FreeSMUG-Free OpenSource Mac User Group build is... Read more
Macgo Blu-ray Player 2.10.6.1691 - Blu-r...
Macgo Mac Blu-ray Player can bring you the most unforgettable Blu-ray experience on your Mac. Overview Macgo Mac Blu-ray Player can satisfy just about every need you could possibly have in a Blu-ray... Read more
Apple Motion 5.1.2 - Create and customiz...
Apple Motion is designed for video editors, Motion 5 lets you customize Final Cut Pro titles, transitions, and effects. Or create your own dazzling animations in 2D or 3D space, with real-time... Read more
A Better Finder Rename 9.39 - File, phot...
A Better Finder Rename is the most complete renaming solution available on the market today. That's why, since 1996, tens of thousands of hobbyists, professionals and businesses depend on A Better... Read more
PopChar X 6.6 - Floating window shows av...
PopChar X helps you get the most out of your font collection. With its crystal-clear interface, PopChar X provides a frustration-free way to access any font's special characters. Expanded... Read more
MacUpdate Desktop 6.0.2 - Install Mac ap...
MacUpdate Desktop 6 brings seamless 1-click installs and version updates to your Mac. With a free MacUpdate account and MacUpdate Desktop 6, Mac users can now install almost any Mac app on macupdate.... Read more

Latest Forum Discussions

See All

Space Colors – Tips, Tricks, Strategies,...
Hello Cadets: Want to know what we thought about this hectic space combat/roguelike? Check out our Space Colors review! Space Colors is a cool shooter/roguelike from Team Chaos. You travel from planet to planet across a huge galaxy and complete a... | Read more »
Tap Sports Baseball – Tips, Tricks, and...
Tap Sports Baseball is a pretty simple game to learn, but that doesn’t mean it’s an easy game to master, by any means. To start your batting career off well, we thought we’d give you the heads up on some handy tips and tricks. Hey Batter-Batter:... | Read more »
Tap Sports Baseball Review
Tap Sports Baseball Review By Jennifer Allen on August 20th, 2014 Our Rating: :: LET'S PLAY BALLUniversal App - Designed for iPhone and iPad Tap Sports Baseball is briefly fun but lacks some important features.   | Read more »
Frontier Heroes Review
Frontier Heroes Review By Andrew Fisher on August 20th, 2014 Our Rating: :: BLAZES NO TRAILSUniversal App - Designed for iPhone and iPad Despite awesome visuals and great music, Frontier Heroes just doesn’t quite deliver enough fun... | Read more »
Echo Prime is Now on Sale for $0.99
Echo Prime is Now on Sale for $0.99 Posted by Jessica Fisher on August 20th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Star Realms Review
Star Realms Review By Andrew Fisher on August 20th, 2014 Our Rating: :: A STAR IS BORNUniversal App - Designed for iPhone and iPad Star Realms is an excellent adaptation of an outstanding deck-builder. With great visuals and an... | Read more »
This. Is. SPRINGFIELD! War comes to The...
This. Is. SPRINGFIELD! | Read more »
One Tap RPG Review
One Tap RPG Review By Campbell Bird on August 20th, 2014 Our Rating: :: DUNGEON SLIDERUniversal App - Designed for iPhone and iPad This casual arcade game introduces some very light rpg elements into its fantasy-themed pachinko... | Read more »
Goodbye Paywall – Table Tennis Touch Eli...
Goodbye Paywall – Table Tennis Touch Eliminates In-App Purchases Posted by Jessica Fisher on August 20th, 2014 [ permalink ] | Read more »
Go to Bed – An Interview With Touchfight...
Touchfight Games is an exciting new indie studio that was co-formed between game journalist and author Nathan Meunier, artist Leonard Kenyon, and programmer Jon Kenyon. Their debut game Go To Bed will be released this fall, and with all the... | Read more »

Price Scanner via MacPrices.net

Apple now offering certified refurbished 2014...
 The Apple Store is now offering Apple Certified Refurbished 2014 MacBook Airs for up to $180 off the cost of new models. An Apple one-year warranty is included with each MacBook, and shipping is... Read more
Best Buy’s College Student Deals: $100 off Ma...
Take an additional $100 off all MacBooks and iMacs, $50 off iPad Airs and iPad minis, at Best Buy Online with their College Students Deals Savings, valid through September 6th. Anyone with a valid .... Read more
MacBook Airs on sale for $100 off MSRP, free...
B&H Photo has three 2014 MacBook Airs on sale for $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 Laptops... Read more
Razer Taipan Mouse For Gamers And Non-Gamers...
If you’re a serious gamer on either Mac or Windows PCs, a serious gaming mouse is a necessity for first-tier performance. However, even if like me you’re not much of a gamer, there’s still a strong... Read more
15-inch 2.2GHz MacBook Pro on sale for $1899,...
Adorama has the new 15″ 2.2GHz Retina MacBook Pro on sale for $1899 including free shipping plus NY & NJ sales tax only. Their price is $100 off MSRP, and it’s the lowest price available for this... Read more
Mid-Size Tablet Shootout Posted: iPad mini wi...
I ‘m curious about how many iPads Apple is actually selling these days. It’s been widely rumored and anticipated that new models with A8 SoCs, 2 GB of RAM, 8 megapixel cameras, and fingerprint... Read more
The 15 Biggest iPad Air Problems And How To A...
What’s this? Fifteen “biggest” problems with the iPad Air? Does that mean there are a lot of smaller problems as well? Say it isn’t so! My old iPad 2 has manifested no hardware problems in three... Read more
TYLT Syncable-Duo, 2-in-1 USB Cable With Appl...
TYLT has introduced the Syncable-Duo, a universal cable solution for charging and syncing data to smartphones and tablets. The Syncable-Duo eliminates the need for multiple cables by incorporating... Read more
Save up to $140 off MSRP with Apple refurbish...
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
2.5GHz Mac mini on sale for $549, save $50
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

Jobs Board

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* Solutions Consultant - Apple (United...
**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
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
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
Project Manager / Business Analyst, WW *Appl...
…a senior project manager / business analyst to work within our Worldwide Apple Fulfillment Operations and the Business Process Re-engineering team. This role will work Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.