RE: Document Conventions

Subject: RE: Document Conventions
From: "Higgins, Lisa" <LHiggins -at- carrieraccess -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 19 Sep 2000 09:23:52 -0600

This is a big bugbear with me, so go ahead and delete me now
if you don't want to hear it.

If you need a section to explain the conventions used in a
document, you need to redesign your document.

I'm not going to say that no user has ever read a conventions
section, but I will stick my neck out and say it's rare.

I do recognize that, sometimes, particularly with complicated
CLI commands and so forth, you need to communicate some
fairly complex things--the basic command, literal and
abstract parameters, and so forth. But I think we're remiss
if we put the burden on the user by requiring them to go to
the front of the book and parse the conventions to the
particular entry. Particularly with information like this,
where users are likely to be looking things up non-serially,
the information should be inclusive.

What I do in situations like this is explain everything that
needs to be explained every single time it needs explaining.

So, I'll show a command like this:

break [intranet | internet] {d}

where the required parameter [intranet | internet] indicates
whether to break your internal network, or intranet; or the
worldwide Infor!Mation!Super!Highway!, or internet. The
optional {d} parameter lets you specify a number of hours,
from 1 to 24, to delay the irreversible destruction of the
specified network.

That's not exactly clean, but you get the idea.

For what it's worth, I've been leaving the document
conventions out for years, and nobody's complained yet. As a
matter of fact, I don't think anyone's noticed at all.


> Hi Everyone, I'm new to the list, and I'm creating a user
> guide. What would
> I put in the Document Conventions section of the document?
> Can anyone help
> me with that?
> Much appreciated. Melissa

This email may contain confidential and privileged
material for the sole use of the intended recipient. Any
unauthorized review, use or distribution by others is
strictly prohibited. If you are not the intended recipient
please contact the sender and delete all copies.

Previous by Author: RE: Usability Testing of Web Sites
Next by Author: RE: Document Conventions
Previous by Thread: re: Document Conventions
Next by Thread: RE: Document Conventions

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

Sponsored Ads

Sponsored Ads