Re: Style guide and/or templates for Technical Instructions

[Janice Gelb <janice -dot- gelb -at- sun -dot- com>]

Paul Abbot wrote:
>
> 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.
>

Most organizations make these decisions for themselves
so I'm not sure there is a generally available "template."
Opinions vary as to how much alternate font to use and
for what items. Some groups like to distinguish anything
other than actual running text with an alternate font to
make these items stand out for the user; others prefer to
limit its use so it has more impact when it is used.

The style guide _Read Me First_ recommends a separate
typographic convention for user input (things in a procedure
that the user is supposed to type) and the industry-standard
DocBook SGML DTD provides a separate entity to do so. The
_Read Me First_ conventions call for an alternate font for
computer-related items such as filenames, commands, and the
like, and alternate font in bold for items the user is
supposed to type. It recommends against alternate font for
GUI items such as menu names or commands because procedures
then become littered with alternate font, which defeats the
purpose of using it in the first place.

As for line breaks, our own house style is to use them
for longer strings or commands that the user has to type
but to leave them in the sentence for one- or two-word items.
And we don't make any distinction for GUI items such as
menu commands. We use Courier as our alternate font.

-- Janice
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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 

Doc-To-Help includes a one-click RoboHelp project converter. It's that easy.  Watch the demo at http://www.componentone.com/TECHWRL/DocToHelp2005

---
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 http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com

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
http://www.techwr-l.com/techwhirl/ for more resources and info.