19
votes
Accepted
Preferred word for "preferred", "target", "chosen" in end user support documentation
One possibility is to not use the adjective: "Select a printer".
Another is to use the adjective appropriate to the action: Sometimes you mean "Select a disk", sometimes (like for formatting) you ...
- 100k
10
votes
Preferred word for "preferred", "target", "chosen" in end user support documentation
All instructions writers wrestle with these terms. Just remember that instructions should be absolutely clear, without ambiguity. "Preferred" can be ambiguous. Does a "preferred" printer stay that way?...
- 1,323
5
votes
Accepted
How to include external references when writing internal documentation?
The guiding principle in my experience is: put the link where the reader needs the referenced information. Examples:
"This interface is like Somebody Else's Thing (link, or make SET a link itself), ...
- 21.4k
4
votes
How to include external references when writing internal documentation?
I like Monica's answer -- my answer here is about how to be sure these links are still viable in the future.
If others are also making the documents, I encourage "casual citation", so there's not ...
- 4,674
4
votes
Accepted
Database documentation verb choice: If "fieldname" has/contains/is/displays
Your first suggestion looks fine. It doesn't seem likely to be misconstrued. There are other similar sentences that would convey the same information in slightly different words, such as:
This tag ...
- 360
3
votes
Database documentation verb choice: If "fieldname" has/contains/is/displays
I would argue against the use of "is" to describe the relationship. There are too many usages of "is" to allow it to be interpreted with the precision that technical writing must ...
- 5,247
3
votes
How to include external references when writing internal documentation?
This depends largely on the way existing documentation is written. Normally you have some kind of template that you can use for most documents. This template should illustrate how to cite external ...
- 5,736
1
vote
What are the recommended sizes for a text box?
For some values, there's a defined length or maximum length. Like US Zip Codes are 5 digits, or 10 digits if you allow for zip-plus-4 and they hyphen. Credit card numbers are typically 16 digits. Etc.
...
- 25.5k
Only top scored, non community-wiki answers of a minimum length are eligible