RE: Style guide and/or templates for Technical Instructions

Subject: RE: Style guide and/or templates for Technical Instructions
From: "Nuckols, Kenneth M" <Kenneth -dot- Nuckols -at- mybrighthouse -dot- com>
To: "Paul Abbot" <datapanix -at- gmail -dot- com>, <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 10 Feb 2006 13:28:31 -0500

Paul Abbot asked...

> Hi,
> I've been elected to create and maintain instructional documentation
> for using various software development tools, like Visual Studio and
> JBuilder. Most of the instructions are of the form "open C++ --> go
> File --> Click New.. --> type filename.txt" with most of the steps
> requiring a checkbox-like bullet so the person following can check off
> each step.
> I'd like to set up a common template to provide a unified look
> throughout the documentation. Is there a guideline, or templates,
> available that can provide information about this. Things like should
> the font change to, say, courier if the user must type something in?
> Or like should the text break when the instruction calls to click a
> button or select a menu?
> I've been told (not a directive, but a suggestion) that "less is more"
> and to not throw 16 different fonts and typesizes in the document.
> while I can agree with not overdoing it, I'm looking at a doc that I
> have started that has *no* formatting, just plain text, and I find it
> very hard to follow. There is no distinction between the text that
> says "do this" and the text that says what the user is actually
> supposed to do.
> I'm using MS Word, but I'm enough of a geek to be willing to dive into
> more beefy stuff like latex. Any insights would be most appreciated!

If memory serves--I'm unable to verify he reference at the
moment--Microsoft Manual of Style (the 3rd party style guide I'm most
familiar with) suggests almost everything the user interacts with in the
GUI be bolded. For example "Click [BOLD]OK[bold] to accept the

For exact text the user types, I believe they suggest using an alternate
font from the body text (e.g., Courier). For example, "Type [FONT]ping[font] and press [BOLD]Enter[bold]."

I agree with the idea that you should limit the number of fonts you
use--just because you have 18,000 fonts loaded on your computer doesn't
compel you to use them in every document you create. Users will get
distracted if you use a different typeface or typestyle for every
different kind of element, and it may detract from the usefulness of
your document.

Every different font or typestyle you use should mean something to the
reader, whether they are conscious of it or not, and the changes should
be infrequent enough that they know it's really important to pay
attention to each occurrence without you having to tell them. All the
same, if your organization doesn't have a style guide in place that
everyone already knows, you should tell your reader somewhere in the
front matter that items which appear in [BOLD]bold[bold] mean "such and
such," and text which appears in [FONT]font name[font] means "thus and

The final word of caution is to make sure you don't give your document a
case of the "measles." If you find you're having to shift fonts and
typestyle several times in each instruction, you're probably overusing
the style and you need to narrow the focus of what you make bold or
change fonts to indicate. Reading a page that shifts in and out of bold
text a lot can be very distracting.

Good luck, and hope this is helpful.

CONFIDENTIALITY NOTICE: This e-mail may contain information that is privileged, confidential or otherwise protected from disclosure. If you are not the intended recipient of this e-mail, please notify the sender immediately by return e-mail, purge it and do not disseminate or copy it.

WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today!.

Doc-To-Help includes a one-click RoboHelp project converter. It's that easy. Watch the demo at

You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit for more resources and info.

Previous by Author: RE: Techwhirlers, re: rude email
Next by Author: RE: The New Communication (was Formality going Bye, Bye)
Previous by Thread: RE: Style guide and/or templates for Technical Instructions
Next by Thread: RE: Style guide and/or templates for Technical Instructions

What this post helpful? Share it with friends and colleagues:

Sponsored Ads