Holly Harkness ([info]atl_stc_prez) wrote,
2007-01-24 21:09:00
  • Previous
  • Memorize
  • Share
  • Next

Technical writing style: 10 rules

Here are ten basic rules I use when writing software instructions.
Most of these are in Microsoft's Manual of Style.

  1. Use an active verb.
    Instead of "The information should be submitted." write "Submit the information."

  2. Don't use the word "should." It introduces uncertainty.
    "The confirmation window should open." (What if it doesn't? Why wouldn't it? etc.)

  3. Avoid the term "the user" in end-user documentation. That's programmer jargon. It's great for functional specs or requirements documents, but when addressing the user, don't use it.

  4. Click a button, not "click on" a button. If the button has a label (for example, Submit) then just say "Click Submit."

  5. Make sure your instructions spell and capitalize GUI buttons, fields, and drop-down menu items exactly as they are spelled on the GUI. If the MULTIPLE OVERRIDE window is all caps, refer to it that way in the manual.

  6. Be conservative with screenshots. You probably don't need a screenshot of the login window if it only has two fields (user ID and password). Nor do you need a screenshot of a "Do you really want to delete this record?" warning box.

  7. Use numbered lists for items that must be carried out in a certain order. Use bulleted lists for those that don't.

  8. Make your instructions task-oriented rather than describing the application itself. If you are writing your manual from the functional specs or the programmer's notes, this is probably the most critical rewrite you'll have to make. The programmer will say, "The Order menu has the following functionality, blah, blah, blah." You will want to write, "To place an order, click Order, blah, blah, blah."

  9. Don't use the word "functionality." Use "feature" or rewrite the sentence completely.

  10. Sleep on it. No matter how much they are rushing you, do not spit out a complicated set of instructions in one day. Take a day to step away from your writing. Then read it over the next morning as if you are reading someone else's work. Does it make sense? Are you missing a key step or piece of information? You'll be amazed at how your quality improves by using this simple mechanism.
So, what are your rules?

  • Post a new comment

    Error

    switch
     
    Help
  • 9 comments

Anonymous

January 25 2007, 13:41:37 UTC 5 years ago

rules of style

Thanks for sharing your rules. I agree with everything you say -- with one small question.

Rule 5 says, "Make sure your instructions spell and capitalize GUI buttons, fields, and drop-down menu items exactly as they are spelled on the GUI. If the MULTIPLE OVERRIDE window is all caps, refer to it that way in the manual."

Let's say that a check box name is "Check spelling during preview" (like the one below this comment box). If I write, "Below the comment box you will see the Check spelling during preview check box," isn't it a little confusing where the adjective ends and the descriptor begins? This is more apparent if the name of the check box is even longer.

This has been a quandary for our style. As a fix, we write "Below the comment box you will see the Check Spelling During Preview check box" -- using the title case for the adjective. But when it's a command, we write "Select the Check spelling during preview check box." The bold sets it off.

I think it's a crazy style discrepancy. My vote was to write the adjective in quotes when it could be confusing, and to keep the case as shown on the screen.

Ideally, I would like to do away with the descriptors altogether, and just write "Select Check spelling during preview." However, that gets a little confusing in places.

This example brings up another style question: Do you select and deselect a check box? Do you check and uncheck a check box? Select and clear a box?

Even more egregious is the name for the "radio button." It won't be long before "radios" go the way of the eight-track -- outdated, old, rarely used. What name do you use for radio button?

Tom Johnson
www.idratherbewriting.com (http://idratherbewriting.com)

[info]atl_stc_prez

January 26 2007, 03:05:02 UTC 5 years ago

Re: rules of style

Tom,
You are raising a different style question IMO.
That is, what conventions do you use to denote buttons, field labels, etc.

In the example you brought up, I would put the label of the check box in quotes (as you suggested), but leave the capitalization as it is on the interface.

My style is to bold button names, links, and tabs — anything that, when clicked, opens a new window or a new section of a window.

Several years ago our team had a lively debate over the use of "deselect." We'd all agreed on "select." Eventually, the "deselect" faction won out.

Radio buttons are "options" in my world. That's Microsoft's recommendation.

hh

Anonymous

January 28 2007, 02:27:47 UTC 5 years ago

Re: rules of style

Thanks for your thoughts on style. I agree with them -- of course getting a dozen writers to agree on a controversial matter of style is next to impossible at times.

Anonymous

January 28 2007, 06:00:37 UTC 5 years ago

Excellent List

I agree 100%. Rule #8 is the most important from a user's perspective, and I have used this as a basis for several document refactoring initiatives in the last several years. With respect to screen shots, I completely agree. Screenshots should only be used when the complexity of a procedure warrants a visual cue. There is no need to bloat a 5 step procedure with captures of each dialog box, status bar, message window, etc.

Aaron Davis
DMN Communications (http://www.dmncommunications.com)

[info]atl_stc_prez

January 31 2007, 11:58:57 UTC 5 years ago

Re: Excellent List

Thanks for your feedback, Aaron.

Anonymous

May 3 2007, 03:18:39 UTC 5 years ago

Re: Excellent List

thanx for that 10 rules you posted it really helped me a lot. I'm actually an entry level technical writer here in the Philippines, and I'm currently searching for guidelines and some advice from experienced tech writers thanx again:-)

Anonymous

December 5 2007, 07:51:45 UTC 4 years ago

Check a checkbox?

The question is still unanswered. Do you check a check cox? Its not wrong, but its a tongue twister, esp. the 'check the check' part. Can we say select the check box? Is it giving a different meaning to what we want the user to do? Please advise.

[info]atl_stc_prez

December 5 2007, 12:07:27 UTC 4 years ago

Re: Check a checkbox?

I recommend "select the check box."
But I think "click the check box" is OK, too.

Anonymous

January 18 2011, 02:39:25 UTC 1 year ago

Grouping Fastness Numbers

I always get high on reading calibre articles nearby an discrete who is certainly up to snuff on their chosen subject. I’ll be watching this direction with much interest. Conserve up the major produce, welcome you next age
[url=http://www.oksingaporeescorts.com]singapore asian escorts[/url]
[url=http://www.oksingaporeescorts.com]escorts singapore[/url]
[url=http://www.oksingaporeescorts.com]singapore escorts agency[/url]
[url=http://www.oksingaporeescorts.com]escort singapore[/url]
[url=http://www.oksingaporeescorts.com]singapore escort agency[/url]
Create an Account
Forgot your login or password?
Facebook Twitter More login options
English • Español • Deutsch • Русский…