terminology question (and a bit of a rant)

Subject: terminology question (and a bit of a rant)
From: Rosemary J Horner <rhorner -at- quellos -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 3 Sep 2002 11:10:27 -0700

Hi everybody,

The first product I wrote help for (6 months ago) has not yet been released.
It's an internal product to be used by one department. The holdup was that
the IT dept wouldn't release it til that department had written a business
process doc that described how it would be used. They're finally doing it,
but what they've done is try to write, from scratch, a "manual" that covers
all the same material I did in the online help (company policy is that help
should only be online, there aren't supposed to be printed versions of
anything because that would make it too easy for people to take home
proprietary application information). And of course, I don't think it's as
good. Not that mine's perfect--there are definitely some things I can learn
from it. As far as I can tell, I'm supposed to review this, then use it as
the help. I'm kind of annoyed. The writing style is very different--there's
lots of unnecessary words, lots of passive voice, lots of bulleted lists
that are part procedure and part information. It's almost worse than
starting from scratch again myself.

Right. So what this has prompted me to do is start a style guide for online
help. I'm the only writer, and I've had my own standards in my head, but
never felt the need to write them down. Now I think it will help me point
out what I see are the problems in this new doc, rather than whining vaguely
that I don't like it :-)

So now I'm trying to define some GUI terminology (our apps are all

- I use "window" to describe popups (big or small) with a Windows standard
blue title bar, and use the title when I'm referring to them. These don't
include the standard browser toolbars, though they're browser windows. The
content of these windows doesn't change (except for input).

- I use "page" to refer to the contents of the main browser window that
does include the standard browser toolbars. The contents, except navigation
elements, can change completely.

- I use "tab" when the interface resembles tabs. Usually this is within a

First, do these definitions make sense to you?

Now, the author of the manual I mentioned above uses "screen" all over the
place, which I haven't been using at all. It's mostly in places where I
would use "window." Is this a standard use of the word screen? Should I
include screen in my style guide even if it's to say "don't use it"? Should
it be used for something else entirely? If pushed, I would think of it in
terms of desktop apps with different views, maybe, but I don't see it with
completely browser-based apps.

I don't have access to the Microsoft Manual of Style or any other style
guides, (but I'm going to request one very soon I think <g>) so I'd really
really appreciate any of your opinions.

Thanks for listening and any advice.


Check out the new release of RoboDemo, our easy-to-use tutorial software.
Plus, buy RoboHelp Office in August and save $100 with our mail-in rebate.
Get details and download free trial versions at http://www.ehelp.com/techwr-l

TECHWR-L is supported by ads and sponsorships...and donations.
You can help maintain the TECHWR-L community with donations
at http://www.raycomm.com/techwhirl/abouttechwhirl/donate.html

You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.raycomm.com/techwhirl/ for more resources and info.


Previous by Author: synonym for "from scratch"
Next by Author: RE: terminology question (and a bit of a rant)
Previous by Thread: RE: HTML Help Author Message
Next by Thread: Re: terminology question (and a bit of a rant)

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

Sponsored Ads