TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
>
> 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
to
> 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.
And
> 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
settings."
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
0.0.0.1[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
so."
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!. http://www.webworks.com/techwr-l
