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

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Monosnap 3.5.9 - Versatile screenshot ut...
Monosnap lets you capture screenshots, share files, and record video and .gifs. Features Capture Capture full screen, just part of the screen, or a selected window Make your crop area pixel... Read more
Tweetbot 3 for Twitter 3.3.1 - Popular T...
Tweetbot is a full-featured OS X Twitter client with a lot of personality. Whether it's the meticulously-crafted interface, sounds and animation, or features like multiple timelines and column views... Read more
Tunnelblick 3.8.0 - GUI for OpenVPN.
Tunnelblick is a free, open source graphic user interface for OpenVPN on OS X. It provides easy control of OpenVPN client and/or server connections. It comes as a ready-to-use application with all... Read more
Bookends 13.2.5 - Reference management a...
Bookends is a full-featured bibliography/reference and information-management system for students and professionals. Bookends uses the cloud to sync reference libraries on all the Macs you use.... Read more
Quicken 2019 5.11.2 - Complete personal...
Quicken makes managing your money easier than ever. Whether paying bills, upgrading from Windows, enjoying more reliable downloads, or getting expert product help, Quicken's new and improved features... Read more
Bookends 13.2.5 - Reference management a...
Bookends is a full-featured bibliography/reference and information-management system for students and professionals. Bookends uses the cloud to sync reference libraries on all the Macs you use.... Read more
Quicken 2019 5.11.2 - Complete personal...
Quicken makes managing your money easier than ever. Whether paying bills, upgrading from Windows, enjoying more reliable downloads, or getting expert product help, Quicken's new and improved features... Read more
Dashlane 6.1927.0 - Password manager and...
Dashlane is an award-winning service that revolutionizes the online experience by replacing the drudgery of everyday transactional processes with convenient, automated simplicity - in other words,... Read more
Capo 3.7.4 - Slow down and learn to play...
Capo lets you slow down your favorite songs so you can hear the notes and learn how they are played. With Capo, you can quickly tab out your songs atop a highly-detailed OpenCL-powered spectrogram... Read more
BetterTouchTool 3.153 - Customize multi-...
BetterTouchTool adds many new, fully customizable gestures to the Magic Mouse, Multi-Touch MacBook trackpad, and Magic Trackpad. These gestures are customizable: Magic Mouse: Pinch in / out (zoom)... Read more

Latest Forum Discussions

See All

Void Tyrant guide - Tips and tricks for...
Void Tyrant continues to get a lot of play in these parts. Probably because the game is just so deep and varied. The next stop on our guide series for Void Tyrant is class-specific guides. First up is the Knight, as it’s the first class anyone has... | Read more »
Summon beasts and battle evil in epic re...
Imagine a tale of conlict between factions of good and evil, where rogueish heroes summon beasts to aid them in them in warfare and courageously battle dragons over fields of scorched earth and brimstone - that's exactly the essence of epic fantasy... | Read more »
Upcoming visual novel Arranged shines a...
If you’re in the market for a new type of visual novel designed to inform and make you think deeply about its subject matter, then Arranged by Kabuk Games could be exactly what you’re looking for. It’s a wholly unique take on marital traditions in... | Read more »
TEPPEN guide - The three best decks in T...
TEPPEN’s unique take on the collectible card game genre is exciting. It’s just over a week old, but that isn’t stopping lots of folks from speculating about the long-term viability of the game, as well as changes and additions that will happen over... | Read more »
Intergalactic puzzler Silly Memory serve...
Recently released matching puzzler Silly Memory is helping its fans with their intergalactic journeys this month with some very special offers on in-app purchases. In case you missed it, Silly Memory is the debut title of French based indie... | Read more »
TEPPEN guide - Tips and tricks for new p...
TEPPEN is a wild game that nobody asked for, but I’m sure glad it exists. Who would’ve thought that a CCG featuring Capcom characters could be so cool and weird? In case you’re not completely sure what TEPPEN is, make sure to check out our review... | Read more »
Dr. Mario World guide - Other games that...
We now live in a post-Dr. Mario World world, and I gotta say, things don’t feel too different. Nintendo continues to squirt out bad games on phones, causing all but the most stalwart fans of mobile games to question why they even bother... | Read more »
Strategy RPG Brown Dust introduces its b...
Epic turn-based RPG Brown Dust is set to turn 500 days old next week, and to celebrate, Neowiz has just unveiled its biggest and most exciting update yet, offering a host of new rewards, increased gacha rates, and a brand new feature that will... | Read more »
Dr. Mario World is yet another disappoin...
As soon as I booted up Dr. Mario World, I knew I wasn’t going to have fun with it. Nintendo’s record on phones thus far has been pretty spotty, with things trending downward as of late. [Read more] | Read more »
Retro Space Shooter P.3 is now available...
Shoot-em-ups tend to be a dime a dozen on the App Store, but every so often you come across one gem that aims to shake up the genre in a unique way. Developer Devjgame’s P.3 is the latest game seeking to do so this, working as a love letter to the... | Read more »

Price Scanner via MacPrices.net

B&H drops prices another $50 on clearance...
B&H Photo has dropped prices on clearance 2018 13″ MacBook Airs by a further $50 with models now available for $250 off Apple’s original MSRP. Overnight shipping, or expedited shipping, is free... Read more
Find the best sales & lowest prices on Ap...
Our Apple award-winning price trackers are the best place to look for the best sales and lowest prices on Apple gear. Scan our price trackers for the latest information on sales, bundles, and... Read more
Apple has clearance 2018 13″ MacBook Airs now...
Apple has Certified Refurbished 2018 13″ MacBook Airs available starting at only $849. Each MacBook features a new outer case, comes with a standard Apple one-year warranty, and is shipped free. The... Read more
Save $400 on the 8-Core iMac Pro today at Ama...
Amazon has the base 8-core iMac Pro on sale today for $4599 including free shipping. Their price is $400 off Apple’s MSRP, and it’s the currently lowest price available for an iMac Pro. For the... Read more
Flash sale! New 11″ 1TB WiFi iPad Pros for th...
Amazon has the 11″ 1TB WiFi iPad Pro on sale today for only $1199.99 including free shipping. Their price is $350 off Apple’s MSRP for this model, and it’s the lowest price ever for a 1TB 11″ iPad... Read more
Weekend Deal: 2018 13″ MacBook Airs starting...
B&H Photo has clearance 2018 13″ MacBook Airs available starting at only $999 with all models now available for $200 off Apple’s original MSRP. Overnight shipping, or expedited shipping, is free... Read more
Apple has clearance 10.5″ iPad Pros available...
Apple has Certified Refurbished 2017 10.5″ iPad Pros available starting at $469. An Apple one-year warranty is included with each iPad, outer shells are new, and shipping is free: – 64GB 10″ iPad Pro... Read more
Apple restocks refurbished iPad mini 4 models...
Apple has restocked Certified Refurbished 32GB iPad mini 4 WiFi models for $229 shipped. That’s $70 off original MSRP for the iPad mini 4. Space Gray, Silver, and Gold colors are available. Read more
Apple, Yet Again, Is Missing An Ultraportable...
EDITORIAL: 07.19.19 Prior to the decision made by Apple earlier this month to retire the thin and light MacBook model with a 12-inch retina display, the Cupertino, California-based company offered,... Read more
Verizon is offering a 50% discount on iPhone...
Verizon is offering 50% discounts on Apple iPhone 8 and iPhone 8 Plus models though July 24th, plus save 50% on activation fees. New line required. The fine print: “New device payment & new... Read more

Jobs Board

Best Buy *Apple* Computing Master - Best Bu...
**711346BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Store Associates **Location Number:** 001095-Chesterfield-Store **Job Description:** Read more
Best Buy *Apple* Computing Master - Best Bu...
**704899BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Sales **Location Number:** 000135-Pleasant Hill-Store **Job Description:** **What does Read more
Best Buy *Apple* Computing Master - Best Bu...
**707083BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Sales **Location Number:** 000045-Rockford-Store **Job Description:** **What does a Read more
Geek Squad *Apple* Master Consultation Agen...
**702908BR** **Job Title:** Geek Squad Apple Master Consultation Agent **Job Category:** Services/Installation/Repair **Location Number:** 000360-Williston-Store Read more
Best Buy *Apple* Computing Master - Best Bu...
**711023BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Sales **Location Number:** 000012-St Cloud-Store **Job Description:** **What does a Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.