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.
Re: Using document conventions from the MS Manual of Style
Subject:Re: Using document conventions from the MS Manual of Style From:Lee Kimmelman <panda -at- WESTSOUND -dot- COM> Date:Sun, 4 Jan 1998 23:29:32 -0800
At 03:49 PM 1/5/98 -0500, you wrote:
>Is it [computer] industry standard to use the document conventions, menu
>terminology and style, etc., as described in the MS Manual of Style?
>Most of my work is software documentation and I've only recently picked
>up the MS Manual. As I read it, all I could think of was, "We don't do
>it that way." Do most TW's follow Microsoft's conventions?
The MS Manual of Style is a valuable tool and goes a long way to helping to
develop a consistent and comprehensive approach to documentation. However,
it (IMOHO) should not be the be all end all resource for the documents you
produce at your company.
First of all, even though a great deal of thought and research went into
the manual's development, that does not mean that it is infallible. We have
all read enough messages on this list and elsewhere expressing the mistakes
that Microsoft has made in the past. Why should their Manual of Style be
exempt from this phenomenon?
Even if it was, the product(s) you are developing are (probably) quite
different from those that Microsoft creates (even if they both are designed
for some sort of Windows environment). Terms that are ideal for MS
applications may cause confusion when applied to your own.
At one of my previous companies, when we decided to revamp our style guide,
the first place we went was to the MS Style Guide. We did a detailed
analysis of it, making four lists:
Styles we use consistently with the MS Manual of Style
Styles we differently but that would benefit from being used the same
Styles we use differently because our product is (was) uniquely different
Styles that do not apply to us.
The first and last lists came easy to us. And most of the styles in the
middle two lists were pretty obvious as well. There were a few issues that
resulted in a flurry of emails and meetings over several weeks before a
consensus was achieved.
In the end, everyone (yes, really) was very happy with the results and we
came out with one of the best documentation sets ever.
