Help Authoring Basics

This forum is for the discussion of the business and craft of writing help. For example writing style, choices of HTML Help or WinHelp or browser-based and so on...

Moderators: Alexander Halser, Tim Green

Post Reply
tinjaw
Posts: 5
Joined: Thu Sep 18, 2003 7:26 pm
Location: Kansas City, MO, USA

Help Authoring Basics

Unread post by tinjaw »

I have spent a couple hours yesterday and today looking for advice for people writing their first user manual. I struck out. I can't even find a place to ask questions. Most of the forums and mailing lists seem to only discuss technical writing as a profession, with job postings and the like. So, it is with hope that I can ask some simple beginner questions here to help me write a decent user manual. I know H&M will help me produce a good "physical" products, so it is help with the content that I seek.

For example, let me start at the beginning. There doesn't seem to be any consistency with even the name of what I am writing. What should I call this?
  • User Manual
    User's Manual
    User Guide
    User's Guide
My next question is about how to work the explanations. I am uncertain as to what voice to use. For example, which angle do you suggest:
  • 1.) You click the Start button to start the server. (and is it "Start button" or "Start Button"?)
    2.) Click the Start button to start the server.
    3.) To start the server, click the Start button.
    4.) Clicking on the Start button starts the server.
Is there one that is considered a best practice in the industry?

I also have a question about the organization. For example, I have a main window with several buttons. Which organization should I use?

1)
Overview
How to do stuff
-- How to start the server
-- How to stop the server
-- How to launch and connect the client
Reference
-- The Main window
----The Start button
----The Stop button
----The Connect button
----The Host IP edit box
Troubleshooting

2)
Overview
Reference
-- The Main window
----The Start button
----The Stop button
----The Connect button
----The Host IP edit box
How to do stuff
-- How to start the server
-- How to stop the server
-- How to launch and connect the client
Troubleshooting

And should I repeat myself or link?

For example, when describing "How to start the server" I will mention the Start button. When I then get to the reference section and get to the Start button, should I repeat my information or should I like to the "How to start the server" topic?

In a perfect world I would be able to download a free PDF with answers to questions like this. Is it a perfect world?

Thank you for spending your valuable time to help get a noob started.
Chaim Krause
User avatar
Dean Whitlock
Posts: 577
Joined: Thu Sep 01, 2005 5:59 pm
Location: Thetford Center, Vermont USA
Contact:

Unread post by Dean Whitlock »

Hi Tinjaw,

The best way to learn is by example, and the help that comes with Help & Manual is an excellent place to start. Our forum moderator, Tim Green, wrote it.

You will also find books about tech writing, some of which I'm sure are very good, though you do have to pay for them. I can't name any, but I'm sure they're there.

As to title, that depends on your taste and the level of detail. A User Guide usually has the basic how-to instructions but doesn't necessarily have all the detailed reference material. A User Manual combines basics and reference. A Reference Manual could either have everything or only have the detailed reference. There are no fixed rules.

How to write? Use your samples 2 and 3. Speak directly to the reader and avoid passive tense and complicated phrasing. Use numbered steps and bulleted items rather than blocks of text. Don't crowd the page/screen: the eye needs white space so it can pick out the important stuff (and have an occassional rest).

In terms of structure, use your first sample, which is pretty much how the H&M help is laid out. It gets people started quickly, then gives them the complicated stuff when they need it. Repeat information where you feel it's necessary. Remember that H&M lets you embed topics in several places so you only have to edit the info once. Learn about invisible topics, pop-ups, and conditional text; they will help you present the info in the best way for the output media.

That's the basics! Just make sure you use enough commas, but not too many. :wink:

Good luck,
Dean
User avatar
Martin Wynne
Posts: 2656
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Re: Help Authoring Basics

Unread post by Martin Wynne »

tinjaw wrote:My next question is about how to work the explanations. I am uncertain as to what voice to use. For example, which angle do you suggest:
  • 1.) You click the Start button to start the server. (and is it "Start button" or "Start Button"?)
    2.) Click the Start button to start the server.
    3.) To start the server, click the Start button.
    4.) Clicking on the Start button starts the server.
Hi,

Describe what the user sees, don't assume what they know. Begin with the desired result, and then explain how to achieve it:

To start the server, click the button labelled "Start" at the bottom right of the dialog.

Now that they know what you mean, you can refer to the "Start" button directly later if necessary.

p.s. I hope this is a hypothetical example -- if your users really need an explanation of the purpose of a button labelled "Start" you have a major task on your hands! :)

Martin.
Post Reply