1

When writing technical documentation, I commonly include articles ("the" and "a"), as I think it makes thigs clear and natural to read:

According to the customer's requirements, the software must be written in the C++ Programming Language.

However, there's a tendency among others on my team to omit articles, and will edit sentences like the one above to the following:

According to customer requirements, software must be written in C++ Programming Language.

Their argument is that it's less verbose, and to them it reads more like other technical documentation they read.

I get the reasons for ommitting articles in headlines, bulleted lists (especially when they're incomplete sentences), etc., but for full sentences that are part of narratives, I think it's better to include articles to improve clarity and make it easier to read.

Are there any authoritative guidelines or styleguides redgarding the use of articles in technical writing?

2 Answers 2

2

It would depend upon whether your writing is to be reviewed for a publication such as a journal. In such cases, their style guide will be your guide.

Assume you are writing for your own, or customer facing documentation. The absence of articles can make your document ambiguous.

To use your example: "the software" will refer to the software for which you are writing the requrements. "software", without the article, implies all software. This could be taken to mean any tools used in the production of the software, e.g. Compilers, testers or even word processors.

I would be wary of omitting articles without giving consideration to the clarity.

3

Google's style guide mentions the use of articles, and is in favor of using them.

https://developers.google.com/style/articles

Key Point: Include definite and indefinite articles in your documentation, and use them correctly.

I have also tried looking at the style guide of some other companies (Microsoft, Apple, RedHat), but wasn't able to find guidance on specifically articles in there.

If your technical documentation is for internal use only, then I'd weigh the opinions of your coworkers a lot more heavily than a style guide. After all, they're the target audience in that case, and not the employees at Google or elsewhere. On the other hand, if the documentation is for sharing outside the company, then outside standards should weigh more heavily.

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.

Not the answer you're looking for? Browse other questions tagged or ask your own question.