Re: Describing field meanings and instructions

Subject: Re: Describing field meanings and instructions
From: Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com>
To: "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 23 Oct 2015 08:01:11 +0000 (UTC)

I consider the meaning of a field more important than any itemized steps listing:1. Enter a value for the Foo field2. Enter a value for the Bar field3. Enable the Baz option...
The first thing we do is use tooltips heavily to document each field. Maybe the user doesn't even need to open the docs.
Once in the docs, the overview for the topic describes what you can do with the particular dialog/screen/group of controls. If I need specific use cases, then I can list them -- if they're small and obvious they can fit in the overview. If not, then I use separate topics.Â

Instead of an itemized procedure, I take a picture and say, "Make it look like this". If one set of controls can have different settings to achieve different results, then I usually give that as a matrix in a table.

In the docs themselves (as opposed to the tooltips) I expand on field descriptions, especially if they require consideration, or have dependencies. This usually makes up the bulk of the "text" for a topic.ÂÂ
Gone are the days when we need to tell people how to use a GUI. A GUI is a language -- the grammar is generally standard. It's the meanings of the nouns, adjectives, and verbs that people need. My opinion.
Visit TechWhirl for the latest on content technology, content strategy and content development |


You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at

Looking for the archived Techwr-l email discussions? Search our public email archives @

Previous by Author: Re: ?What we need is a developer who can write.?
Next by Author: Into the Frying Pan
Previous by Thread: RE: Describing field meanings and instructions
Next by Thread: Design templates

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

Sponsored Ads