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 ...
user avatar
  • 93.2k
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?...
user avatar
  • 1,260
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), ...
user avatar
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 ...
user avatar
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 ...
user avatar
  • 250
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 ...
user avatar
  • 4,904
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 ...
user avatar
  • 5,596
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. ...
user avatar
  • 25.2k

Only top scored, non community-wiki answers of a minimum length are eligible