4

So I'm a software engineer and I was recently writing some documentation about an application. Said application has some functions/classes/etc whose names are overloaded with common English words and words that are commonly found in the software development environment, like "job" and "component".

While writing, without putting much though into it, I used the convention of capitalising the first letter of the app-related terminology to distinguish it from the normal English. E.g. "You can also start a Job from the GUI", where "Job" here referes to the application-specific notion of a job.

However, while reviewing the documentation, one of my coworkers challenged my convention of capitalising the first letter of those words, and another suggested that the correct convention might be italicisation instead. None of us were sure, though.

So, is there a convention for this? Was capitalisation okay, should I be italicising instead, or is the solution something entirely different?

Improve this question
10
  • 1
    Welcome to EL&U. This is not really a question about the English language, but about its presentation, and as such it is purely a matter of style. Adhere to the discipline of your editor, publication, or organization, or in the absence of a house style, adopt an appropriate style manual and be consistent in its application. Furthermore, the conventions you use will likely vary depending on whether the documentation is in a printed handbook, a website, a man page, README.md, and so on.
    – choster
    Commented Jan 12, 2018 at 19:09
  • 1
    If you're trying to disambiguate concepts specific to the application from their more commonly used counterparts, consider qualifying them with the application and/or class name instead, e.g. "The Frobozz component launches a Frobozz job when you tickle its frenulum."
    – Gnawme
    Commented Jan 12, 2018 at 21:10
  • 3
    Somebody has been here before you, so learn from them. If you still have a software manual from Apple or Microsoft, or an O'Reilly programming book, look and see how they define different types of technical words. Otherwise, try the Apple Developer's site for similar information. At the end of the day it is subjective, but the big boys have gone to a lot of trouble and expense to make their documentation clear, so you are unlikely to do better.
    – David
    Commented Jan 12, 2018 at 21:46
  • 3
    +1 for wanting to improve the clarity of your software documentation, and for asking this specific question. Capitalization isn't needed if you use the terms in context. Think about the structure of your descriptions. If you are narrating a process, do it from a consistent viewpoint, and in a forward-moving sequence of events. "Style" guides are useful, as others have pointed out, but good narration is something else.
    – user205876
    Commented Jan 12, 2018 at 22:16
  • 1
    If Logician had a style guide s/he wouldn't be asking. Writers suggest capitalization. Purdue OWL offers this advice.
    – MikeJRamsey56
    Commented Jan 12, 2018 at 22:19

0

Reset to default

Browse other questions tagged .