Re: conventions

Subject: Re: conventions
From: Barbara Roll <broll -at- MICROSOFT -dot- COM>
Date: Tue, 2 Jun 1998 13:21:05 -0700

When the Microsoft Style Guide says "Use only in technical documentation,"
it refers to developer documentation, where its use is appropriate for
teaching the developer about using the control. In documentation for anyone
other than developers and programmers, Microsoft standards call for the use
of simpler terms, such as list or box. In some cases, you can get away
without referring to the control at all. ("For File name, type a name for
the new document.")

-----Original Message-----
From: Kippi Fagerlund [mailto:KippiFa -at- ATTACHMATE -dot- COM]
Sent: Tuesday, June 02, 1998 1:04 PM
To: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
Subject: Re: conventions


> -----Original Message-----
> From: Mike Stockman [SMTP:stockman -at- JAGUNET -dot- COM]
> Subject: Re: conventions
>
> Heck, *I* didn't even know what a spin box is (although now that I've
> looked it up in the Microsoft style guide I get it). As in most cases
> of
> cryptic, jargon-y words and phrases, this shouldn't be used for
> readers
> who don't already know it, conventions page or no conventions page.
> The
> Microsoft style guide even says about spin box, "Use only in
> technical
> documentation." Even in a technical doc, I'd put it in the glossary to
> be
> safe.
>
> Why make the user turn to a Conventions page when you can simply
> re-write
> to avoid the jargon? I'm still of the opinion that Conventions pages
> usually either state the obvious or compensate for unclear writing.
>
> ----->Mike
>
>
I find using words like spin box, combo box, text field, etc.
useful when documenting
a user interface. Some of these elements have subtle behavior
differences, and if
they are described consistently, a user knows something already
about how particular
things work when encountering a new dialog.

I'm also in favor of conventions pages. If you don't need it,
you won't read it, but it'll be
there for other users.

Kippi


Kippi Fagerlund
kippi -at- eco -dot- twg -dot- com
Attachmate Corporation
McLean, Virginia





Previous by Author: Re: QUERY: which intranet book?
Next by Author: Re: Question: 1099 status and agencies
Previous by Thread: Re: conventions
Next by Thread: Re: conventions


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


Sponsored Ads