15

Some terms in technical documentation, for example product proper names, should obviously be capitalized. But there are other terms that are somewhere between a proper name and a generic noun: domain terms more or less specific to a given product, but are not proper names per se.

For example in developer documentation for CMS software these might be: class, controller, repository, etc.

On one hand, capitalizing such terms makes it explicit to the reader that we are referring to the name in the specific context of our application (e.g., the content Repository of our product, not a GitHub repository).

On the other hand, there is no grammatical reason to capitalize them, and overfilling a text with capitalized terms can increase cognitive load and make it harder to understand.

What do I need to consider when creating guidelines for capitalizing such domain terms?

Improve this question
2
  • @choster, most communication questions don't have a single verifiable answer. They have a set of alternatives with pros and cons for each. Software executes on a single architecture. Communication is received by a widely varied audience that understands and reacts differently. There are no single verifiable answers. There is a different answer for every reader and none of them are easily verifiable.
    – user16226
    Jan 26, 2018 at 12:43
  • @MarkBaker I participate primarily on non-technical stacks, and am thus aware that there is some subjectivity in topics where you cannot plug answers into a compiler. But there is a difference between asking for advice and asking for suggestions. Asking for pros/cons turns the question into a guessing game; the "best" answer easily becomes either the one that comes last and incorporates all previous answers that have already been given, or the one that confirms the original bias of the asker. But the OP's edit is good enough for me for private beta :).
    – choster
    Jan 26, 2018 at 15:40

1 Answer 1

Reset to default
9

Pros:

  • Makes the context of the term explicitly clear.
  • Visually points attention to important terms.

Cons:

  • Over-capitalization reduces the readability of text.
  • Capitalization does not designate a term but a proper noun. This suggests that you are speaking of a named product/service/entity, or even worse - personalizing the term in question. This might lead to confusion, or even raise legal issues. (For example: if another company has coined The Term, and you go and use it as The Term in your text.)
  • Capitalization is a way to draw attention and emphasize the capitalized text. It might draw the reader's attention away from more important text, hidden within regular formatting and capitalization.

In general, this approach is not advisable. Using a more explicit term (for example: "the content repository" or "the actual-name repository" instead of the "repository") would be the way to go. A dedicated Glossary is also a good practice. Furthermore, readers are aware of their current context and where misinterpretation or confusion is likely, it is best to rework the text to avoid it.

Improve this answer
1
  • Fix the the text rather than rather than rely on some device/style/trick to make it work is the hard answer that's still better than the easy answer.
    – user25452
    Feb 7, 2018 at 22:13

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.