Software Product Documentation

How to Hire the Right Technical Writer

2005-07-12T13:48:00.000-04:00

Do not ask them which tools they know.
Ask them how they would go about picking the right tool for a project.

Do not worry about whether they understand your business (although this is helpful). Ask them whether they understand your customers, and how they will go about learning if they don't.

Ask them for samples. Do not worry if they don't look like yours. Ask them what the strategy was and why they picked this format and approach.

One Quick and Sneaky Tip For Screening Candidates: Hiring a writer can go a lot more quickly than you think, because the minute a resume hits your inbox, you'll be able to evaluate a lot more than just work history; you'll be able to tell something about skill level just from the way the document was created.

Ask for a resume in Microsoft Word format. Open it, and from the View menu, click Document Map. If the writer has properly applied styles (and you always use styles, not local formatting, in properly prepared documents intended for reuse and/or production) then you will see on the left side of the window a very nice outline view, which corresponds directly to the subheadings used in the resume. For example, you ought to see Employment History, Education, Professional Activities, and so on if those items were used as subheads. If you don't see all the items in the outline view, then local formatting was used. Bad, bad writer. Next.

Return on Investment in Technical Documentation

2005-07-12T12:24:00.000-04:00

Do you view your technical documentation as just another software requirement? A necessary evil? A construction expense?

Au contraire...you can actually make money on your documentation. Here's how you improve your bottom line.

The first step is to make sure you are not thinking of the documentation as an add-on to your software product. Any user assistance you provide, whether it's online help, a paper guide, or the user interface itself, IS the software. Every line of text counts, just as every line of code does.

The second step is to understand that the value of great documentation isn't going to immediately jump out at you when looking at your income/expenses statement. That's because unless you are selling documentation separately--and usually you are not--you cannot ascribe income directly to the documentation line item. You can however, ascribe expenses, and this is where Managers on Missions to Improve the Bottom Line tend to make critical errrors. They can see that documentation expense line item, and they start thinking all kinds of Dark and Dastardly Thoughts about slashing it. Big mistake. What they should do, instead, is jump right on over to the customer support expense line, and ask how that can be reduced. Because that's where the problem is...and every dollar you invest in improving your user assistance tools (whatever form they might take) is going to pay off--and not only in customer support cost avoidance.

Step three: Documentation SELLS, and is therefore a way to bump up that revenue line item. All other things being equal, in a competitive situation, the product that demonstrates usable, user-friendly documentation and help features has an edge. And even if they are not equal, the product that looks better--the one that has a friendly interface with consistently and accurately labeled fields, perhaps tool tips, and a good help sysem--is going to appeal more to the business buyer, if not the IT folks. Consider your documentation A Feature of Enormous Importance, and play it up. If you are at all in doubt about consumer desire for good documentation, hie thee over to to your local bookstore and browse the aisles of computer software how-to books.

Fourth, realize that it's not fair to expect your development team to provide documentation. They can't write great code and great docs at the same time. Invest in professional writers who know their stuff.

Separation of Content and Format

2005-05-23T22:01:00.000-04:00

Among communications pros, the debate about separating content and format can get as vociferous as the ones about church and state. Purists believe that writing is writing, and as such is Done by Writers, whereas formatting is a secondary and more mechanical activity, part of the production function and therefore properly done by Lesser Beings.

I have never been able to think this way. Even if I am on a project where I'm only doing the writing part, I am always envisioning the completed, published piece, creating visuals in my head about layout, and where the page breaks should be, and wouldn't this be a fabulous place for a callout...

I think this is because I believe that communications are achieved with more than just words; matters of accompanying art, white space, and column width all have the power to send messages too. So I concern myself with the entire message, not just the text. In The Blackwell Encyclopedia of Writings Systems, Florian Coulmas defines a writing system as a set of visible or tactile signs used to represent units of language in a systematic way, with the purpose of recording messages which can be retrieved by everyone who knows the language in question....
icons, graphics, and page layout are all signs used to represent language too.

Of course, if you are in the market for A Writer Who Just Writes, pleased be assured I am very capable of keeping my stray thoughts about format to myself :-)

Communicating With Art

2005-05-21T22:07:00.000-04:00

When I was 17, my commercial art class had an end-of-term assignment: to create a cover for the Senior Awards Night program. Each student would submit an entry to the guidance counseling staff, which would choose the winning design to be printed on the cover of the program.

Now, my commercial art teacher had always been particularly verbal about my Notable Lack of Talent. It had been a miserable year in her class, and my lifelong love of creating art was crumbling under the weight of her withering criticism. My stuff wasn't esoteric enough, it had No Soul, it was bland and boring. Probably I should Find Something More Appropriate to do with my life, such as secretarial work. Nevertheless, there was this final asignment to be gotten through, and as she oohed and ahhhed over other students' drafts, I sat in a corner and stopped trying to please her. I drew what came to me, and turned it in listlessly.

A few weeks later, Ms. Hahn (I shall never forget her) announced to the class with great disgust that a winner for the contest had been chosen, an entry that she found singularly unrepresentative of the talent in her class. She was Quite Sorry for all of them about it, but there was nothing she could do. "It just goes to prove," she sniffed, "that Great Art doesn't sell." And then she unveiled the winning entry: mine.

It's a great cliche that in moments of embarrassment, one wishes the floor would open up and swallow you, but that is exactly how I felt; not only that day, but at the actual awards night, as the program, with my design filling the entire front cover, was handed out to the parents and aunts and grandmas and brothers streaming in. Why, oh, WHY, hadn't I signed my name much, much smaller, so people wouldn't notice it was my work?

It took me years to figure out that Mrs. Hahn had it, and me, all wrong. It was, after all, Commercial Art: that is, art which is pressed into service in order to move people to do something, whether to buy product, read a little farther along, or listen to the commerical a little bit longer. As distinguished from Fine Art, which also makes a statement and hopes to move people but with less of an ulterior motive, commercial art has much more demanded of it. It must create a spark of recognition of the message; it must communicate in such as way that the viewer, or customer, resonates to something in it, and takes some action. And the art must do this quickly--in the time it takes to turn a page, or flip the channel, or click Next. There is no time for Standing About in Museums, Pondering Meaning. It has only a moment to speak its message and hope for a response.

The design that won the competition that year was nothing fancy, and my execution wasn't great, but I know now that it won because it worked. The year was 1976; the nation was brimming with nostalgia, celebrating the American bicentennial, and ours was the first class to graduate having spent all four years attending that school. My design incorporated elements of the traditional parchment diploma, represented as a tattered, unfurling scroll, such as the Declaration of Independence might have been written on, with a quill and inkwell beside it. It fit the mood, it fit the time, it fit the occasion; that's why it won.

The real moral of this story is that great commercial art always sells. And if, somewhere in a dusty attic, somebody's mom saved a copy of that program, I know that my classmate, whoever they may be, will unfold the thinning, faded paper, and remember well a night in 1976.