How should important terms be emphasized in documentation?

Question

Software will often introduce and formalize concepts that may have ambiguous definitions in the real world. For example, in an attendance tracking system, an Occurrence refers to an Excused Absence, an Unexcused Absence, or a Tardy.

In technical documentation (both in helper text and in user guides, etc), should these concepts be proper nouns, and as such, should they be capitalized in usage?

In other words, which of the following examples is more appropriate:

After an Occurrence has been created, it may be converted into an Excused Absence once the Approval Form has been uploaded.

or

After an occurrence has been created, it may be converted into an excused absence once the approval form has been uploaded.

Answer 1

If the term means something more specific to your usage than the commonly-accepted definition of the term (alternatively, if your definition of a term is different than the commonly-accepted definition), it should be capitalized as a proper noun.

IMHO, anyway.

Answer 2

I have capitalized these terms for years. It seems to work.

I have the impression that legal documents do something similar when assigning a precise meaning to an otherwise-common word.

Answer 3

Sometimes a phrase is just a phrase, even though its referring to something important to you. With the exception of "Occurrence," I don't think those nouns are particularly proper. "Excused absence" and "approval form" are descriptive as ordinary noun phrases; if I came across these in their capitalized form, I think I'd wonder if they're oblique references or outright euphemisms. (On the other hand, if "Approval Form" is the actual title of a form, try Approval Form instead.)

"Occurrence" is problematic, however. Usually, occurrence means "something that occurs," which is vague to the point of meaninglessness. In this case, you have the opportunity to be much more descriptive without repurposing an existing word. Try "attendance record" or "attendance event." It's clearer and doesn't require awkward capitalization.

Answer 4

As the use of the word is specialized, this needs to be made clear to the reader. I would not only capitalize these terms, but use a different font/style to highlight that these are specific terms used in context.

Answer 5

After an Occurrence has been created, it may be converted into an Excused Absence once the Approval Form has been uploaded.

The above example would be the way to go as long as the emphasized terms are meaningful within your system.

Perhaps having a glossary of the technical terms where Capitalized and italic terms would be defined to help the user find the correct term usage and meaning for your system.

Another solution I most of the time use is a retirement in the margin with an information icon to denote something important. Then defining your terms within these tips could be more pedagogical somehow. In little of what we're trying to do when using blockquotes in SO. =)

Answer 6

My opinion is that in an ideal documentation, these terms should be included in a glossary at the end. Then all the occurrences of them become hyperlinks and are displayed differently from ordinary words, for example in blue or with an icon.

The use of a glossary makes ambiguous terms not an issue anymore. The user can find out the "local" definition of the term in the document, simply by clicking on it.

Answer 7

First of all, to your question:

Yes, make these emphasized.

Any mission/business-critical concept that appears multiple times in your documentation should generally be unambiguous and well-defined. Part of your goal with documentation is to ensure that readers would over time learn these terms and their meanings, and be able to quickly detect issues in the documentation or the underlying system. Emphasizing a word when it serves as one of these domain nouns helps ensure that readers give it the appropriate consideration.

In the cases that a term can appear both as a domain noun and also as an unrelated natural text, it is advisable to get rid of the unbound name to reduce confusion. If it is not possible to do so, then having a visually clear way of distinguishing between the two is critical, hence emphasizing makes sense. Think about the way modern IDEs distinguish general identifiers from keywords, or how they distinguish variables from members. Visual cues are the among the best ways to disambiguate things.

If you are distributing electronic documentation in addition to printed (I hope you are), then you probably want each instance of the well-defined term to be linked to some glossary. In that case, you would be providing something like a hyperlink or an indication, so you could skip the caps.

Now something more general:

I did my Ph.D. work on how people read API reference documentation (JavaDocs in this case). While this doesn't apply directly to the situation you're describing, some of my general findings might (with no guarantees).

I found that when people choose to read a piece of text, they already have a goal in mind, and they also have a preconceived notion of what that text would say. As a result, they are more likely to miss anything that is not in their expectations, even if it is starting them in the face and sometimes even after repeated readings.

For instance, suppose that I am reading the instructions for "how to charge an electric car". I would come in expecting to see something about turning off the car, plugging it in some way, paying in some way, and waiting a certain amount of time. I will likely be scanning the text for that. If there is a line somewhere like "make sure that the car temperature is below X before proceeding", I would be more likely to miss it because I'm not looking for it.

What I'm trying to say is that your goal as documentation writer is not to cover your bases (legal is for that), but to ensure that someone who is skimming the text (and most people would be skimming) would get the most out of it. This means that your focus should be on emphasizing things that are likely to be unexpected, and any trick in the book is good for that, including caps, words like "warning!", "make sure that", etc.

After you write your documentation, do actual usability testing. Give a coworker (or more than one) who's not familiar with the business process 10-15 seconds to read something like your occurrence paragraph, then ask about the special clauses there. If you see that enough people missed that, consider emphasizing the unexpected.

Answer 8

1. If you have these vague terms, create a special style for them. Use different font style, or make it italic, or whatever. It's probably better to capitalize, but capitalization alone wouldn't solve the problem, because sometimes Occurrence can be the first word in a sentence, for example.
2. Create a glossary for your documentation. It should have all these vague terms and provide definitions for these terms within your system.
3. Separate "terms" from UI elements by using different styles. The"Approval Form" looks more like a UI element, so I would use bold here.
4. Try to avoid giving instructions in such unstructured sentences, especially when you are dealing with vague terms.

After an Occurrence has been created, it may be converted into an Excused Absence once the Approval Form has been uploaded.

Should be more like:

Creating an Excused Absence

a. Create an Occurrence.

b. Upload the Approval Form.

c. Convert Occurrence into Excused Absence.

Hope this helps.

Answer 9

Yes, you should capitalize them.

It is also widely accepted to italicize such domain specific terms.

Answer 10

I think that if this sentence is in any kind of user guide, you should not capitalize it. I mean, if you you were in a developer help file, or in comments in the code, this is appropriate cause he will understand the the reason or the sense of the capitalization.

For an user, there's no doubt for me that he shouldn't read it this way. You have to put yourself in his position. It's not normal, it's even an orthographic error which could lead to a bad interpretation of your purpose.

Answer 11

The answer is "both."

You did not specify that target of the text. As stated, the medium is the message, and the perception and presentation of this documentation is different if by HTML, PDF, paper, or video. Your example implies that this is a time and attendance system. I think it is safe to assume a time and attendance system will be web based. As such, capitalization is less important than the link context.

Capitalized terms are often used in legal documents and contracts. The sentence "The sale of the assets of the business will include the cash." may be very different than The Sale of the Assets of the Business will include the Cash. Lawyers understand the capitalized terms to mean a reference to a contractual defined term versus the layman's experience of that term. The defined term for Cash may be more or less inclusive than cash.

In a time and attendance system, you will have the terms that are both lay terms (absence) and terms that are defined in state law, federal law, or the employee handbook (Absence).

Assuming that the primary target of the documentation will be a dynamic document (Web or PDF) I think that you should adopt the following convention:

1) Have the defined system terms (created) in a specific link text with color or italics to set it off from other text. Clicking that link gives you further information relevant to that term.

2) Have the client's HR terms or terms that may refer to a definition of law or contract as capitalized terms. These terms may coincide with system terms or verbs. Have the either the system help of capitalized term definition as one link through and the other revered from the second link.

So your example would be:

After an occurrence has been created, it may be converted into an Excused Absence once the Approval Form has been uploaded.

In this case, software or system terms are linked and italicized; defined terms are linked, capitalized and bolded. Wikipedia presentation is a great example of the convention I have explained here.