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.
Sanjay Srikonda wrote:
> so, is the general consensus that document conventions are good or bad? I'm
> thinking about including one in my main application help so that users can
> better use the help. The only convention I'm using currently is including
> text messages that are generated by the system in a Courier font as opposed
> to the Arial font as in the rest of the help.
Of course, I don't know the context, but this sounds like a
convention that you could do without. Do users really need to be
able to pick out the text messages from the rest of the manual?
Anyway, English already has conventions for presenting
quotations, including quotation marks and block quotes. Why not
simply say something like, "A dialogue box displays, asking 'Are
you sure you want to quit?'"
As for document convention sections, I think that it might be
very useful for write that section - but for yourself, not for
users. Users can pick up many of the conventions without being
told them specifically. At other times, Lisa's habit of
explaining everything in context is also a good idea, since you
can't expect everyone to read or remember the document convention
Bruce Byfield, Outlaw Communications
Contributing Editor, Maximum Linux
bbyfield -at- axionet -dot- com | Tel: 604.421.7189
"But why ask questions now, and yet there's no denying
There's emptiness in heart and soul
When someone's been deceived."
- Eileen McGann, "Westminster Bridge"