TweetFollow Us on Twitter

March 93 - Editor's Note



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


Community Search:
MacTech Search:

Software Updates via MacUpdate

Facility 47 (Games)
Facility 47 1.0.1 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0.1 (iTunes) Description: You wake up alone and freezing in an icy cell. You try the cell door but it’s locked, it seems that you are stuck with no... | Read more »
The best Photoshop alternative on iPad
Instagram and Lightroom are great and all, but sometimes people need to get extra creative with their image editing.Like, Photoshop creative. If you're one of these people, take a look at our pick for the best mobile Photoshop experience on iPad... | Read more »
The Walking Dead: No Man’s Land guide -...
A new update for The Walking Dead: No Man’s Land was released last week, making it the perfect time for you to head back to your base and take out some walkers. Here’s the lowdown on what’s new to the game, and how to take advantage. [Read more] | Read more »
Goat Rider guide - Tips and tricks to st...
We've all been there. One second, we're riding high on a crazed goat, and the next, we've been tossed off it like someone who's no good at goat ridin'. [Read more] | Read more »
Real Boxing 2 CREED: How to become a gre...
Just in time for Rocky fans who can’t wait to see CREED, the latest movie, we have the official tie-in game,Real Boxing 2 CREED. It builds on the success of its predecessor and there’s lots to take in so we at 148apps thought we’d run you through... | Read more »
CoinOp Heroes 2 guide - How to build an...
CoinOp Heroes 2 justlaunched and, like all clickers, it's dangerously addictive stuff. You have to furiously tap your screen to defeat wave after wave of foes and earn an insane amount of cash to spend on character upgrades and an army of minions... | Read more »
Dr. Panda Firefighters (Education)
Dr. Panda Firefighters 1.0.1 Device: iOS Universal Category: Education Price: $2.99, Version: 1.0.1 (iTunes) Description: FIGHT FIRES AND SAVE THE DAY!Work together with Dr. Panda and his firefighting team to rescue his trapped... | Read more »
Puddle + (Games)
Puddle + 1.0 Device: iOS iPhone Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Puddle is back in a new "+" edition featuring enhanced graphics, new videos and Apple TV support ! No IAP and No Ads. Dive into Puddle... | Read more »
Football Manager Mobile 2016 (Games)
Football Manager Mobile 2016 7.0.0 Device: iOS Universal Category: Games Price: $8.99, Version: 7.0.0 (iTunes) Description: Football Manager Mobile 2016 is designed to be played on the move and is the quickest way to manage your... | Read more »
Kill Shot Bravo guide - How to become an...
Kill Shot Bravo is a disturbing amount of fun. No matter how many times I play a game that encourages me to snipe people in the head, I feel a little uneasy at how satisfying it is. Here are some useful tips to get you started on your path to... | Read more »

Price Scanner via

Adorama Black Friday deals: Up to $400 off Ma...
Adorama has released their Black Friday deals for 2015. Save up to $400 on MacBook Pros, $200 on MacBooks and MacBook Airs, and $270 on iMacs. Use code RYBFDEAL during checkout to see these prices.... Read more
B&H Photo Deals: $200 off 12-inch 1.2GHz...
In addition to the B&H Photo Black Friday week sales we posted yesterday, B&H has lowered their price on two products to $200 off MSRP: - 12″ 1.2GHz Gray Retina MacBook: $1399 save $200 - 13... Read more
Best Buy Early Access: Today only, Up to $125...
Best Buy has iPad Air 2s on sale for up to $125 off MSRP and Apple Watch models on sale on their online store for up to $100 off MSRP with special codes through midnight CT tonight. Choose free... Read more
UPPERCASE DESIGNS Premium Ultra Thin Keyboard...
UPPERCASE Designs today announced its new Premium Ultra Thin Keyboard Protector and its Palm Rest Protector Set for the 12-inch MacBook. The accessories provide durable protection for the 12-inch... Read more
Al Jazeera Launches New iOS And Android Mobil...
Doha, Qatar based Al Jazeera has launched new mobile and tablet apps on the iOS and Android systems bringing the latest Al Jazeera news and programmes live together with on-demand personalisation.... Read more
B&H Photo Holiday Sale: Up to $250 off Ma...
B&H Photo has all new Macs on sale for up to $500 off MSRP as part of their Holiday sale including free shipping plus NY sales tax only: - 15″ 2.2GHz Retina MacBook Pro: $1799 $200 off - 15″ 2.... Read more
Free Aura ‘Ultimate’ Mac App For Gmail Update...
Miami, Florida based Crosscoded has announced Aura 1.2.0, an update to the Mac app for Gmail. Aura mixes the power of a native client with the flexibility of the Gmail web app with support for up to... Read more
Apple Will Edge Closer to Samsung in Smartpho...
Total smartphone shipments for 2015 are projected to decline by 9.7% to 1.286 billion units, according to the latest report from global market research firm TrendForce. Though Chinese vendors have... Read more
Sidefari – Split Screen Multitasking In Safar...
Francisco Cantu’s Sidefari is a simple web browser designed to act as a companion to Safari on the iPad. With multitasking in iOS 9, Sidefari uses the new Safari View Controller to show an extra... Read more
12-inch MacBooks in stock for up to $120 off,...
Adorama has 12″ Retina MacBooks in stock for up to $120 off MSRP including free shipping plus NY & NJ sales tax only. For a limited time, Adorama will include a free Apple USB-C to USB Adapter,... Read more

Jobs Board

*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
Merchant Operations Manager: *Apple* Pay -...
Changing the world is all in a day's work at Apple . If you love innovation, here's your chance to make a career of it. You'll work hard. But the job comes with more than Read more
*Apple* Pay QA Manager - Apple Inc. (United...
Changing the world is all in a day's work at Apple . If you love innovation, here's your chance to make a career of it. You'll work hard. But the job comes with more than Read more
Sr Software Engineer *Apple* Pay - Apple In...
Changing the world is all in a day's work at Apple . If you love innovation, here's your chance to make a career of it. You'll work hard. But the job comes with more than Read more
Hardware Systems Architect - *Apple* Watch...
# Hardware Systems Architect - Apple Watch Job Number: 38449977 Santa Clara Valley, Califo ia, United States Posted: Apr. 16, 2015 Weekly Hours: **Job Summary** The Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.