RE: Conventions

Subject: RE: Conventions
From: "Joe Malin" <jmalin -at- tuvox -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 27 Jul 2005 11:59:42 -0700


These are from MS Manual of Style 3rd Edition:

title: default font, bold, "...the *Main Widget Administration*
window..." (* indicates bold)

key: depends on usage. If you use Press, key name in all uppercase, no
bold. If you use Type, use lowercase bold unless a specifically
uppercase is needed.
Press Y
Type *y*.
At first use, you may use "the F1 key"; afterwards, use "F1"
you will need the MS reference for the key names

button: rectangular buttons are "command buttons". Refer to by name,
without "button", and use the verb "Click". "radio" buttons are "option
buttons." Refer to by name, without button, and use Click.
label is in default font, bold.

system and error messages: set off on a separate line, use screenshot,
or put in quotes. Do not use special formatting. If the error message is
in the context of console or printer output, >I< use the same font as
the rest of the output.

Text the user needs to type: use bold for exact text, use italic for
text that the user needs to replace with the exact value. Use Type as
the verb (but personally, I use "Enter").

The MS Manual of Style isn't as specific as you might think!




Joe Malin
Technical Writer
(408)625-1623
jmalin -at- tuvox -dot- com
www.tuvox.com
The views expressed in this document are those of the sender, and do not
necessarily reflect those of TuVox, Inc.

-----Original Message-----
From: bounce-techwr-l-216553 -at- lists -dot- techwr-l -dot- com
[mailto:bounce-techwr-l-216553 -at- lists -dot- techwr-l -dot- com] On Behalf Of Suzette
Leeming
Sent: Wednesday, July 27, 2005 11:07 AM
To: TECHWR-L
Subject: Conventions


I am in the process of setting up documentation conventions, and I'm
questioning my current conventions and can't find my MS Manual of Style.

So I thought I would ask the experts....

How do you refer to/depict each of the following:

- The name/title of a window (The Main Widget Administration window)
- A key on the keyboard (i.e., press Enter, or F1, etc.) (I used to put
in square brackets and bold)
- A button in the application (i.e., click Continue)
- System and Error messages (I usually use Courier)
- Text the user needs to type (Type: /u/public)

I know the important thing is consistency and I AM consistent, but since
I'm just starting to set this up, I thought I would see what type of
conventions others used.

If this type of question bothers you, please feel free to delete this
message without responding. Thanks in advance to those who will take a
moment to answer!!

Suzette Leeming
Stouffville, Ontario

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Now Shipping -- WebWorks ePublisher Pro for Word! Easily create online
Help. And online anything else. Redesigned interface with a new
project-based workflow. Try it today! http://www.webworks.com/techwr-l

Doc-To-Help 2005 now has RoboHelp Converter and HTML Source: Author
content and configure Help in MS Word or any HTML editor. No
proprietary editor! *August release. http://www.componentone.com/TECHWRL/DocToHelp2005

---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -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.



Previous by Author: RE: Declining a copyediting test
Next by Author: RE: SDK documentation
Previous by Thread: RE: Conventions
Next by Thread: Re: Conventions


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


Sponsored Ads