The Elements of Technical Writing Style
- Read the instructions
- Always check your work
- The rules of grammar still apply
- All documents must have headings
- Use headings meaningfully
- Use headings in order
- Never put links in headings
- Never put colons at the end of a heading
- Avoid shouting in headings
- Use lists for lists
- Avoid writing like an AI robot
- Use meaningful link text
- Avoid raw link URLs
- Consider formal citation styles
- Publish in an appropriate format
Part of your job as a well-rounded person of interest is to write documents and documentation clearly and effectively. Writing is a form of communication, where the goal most often is to have others understand what you have written and why you have written it. This means deliberately structuring documents thematically into sections and sub-sections that serve an organizational purpose that aligns with your intent, as well as ensuring that the content within these sections and sub-sections is intelligable to the viewer.
Communicating clearly and with purpose is something that we strive to do as computer scientists, software engineers, data scientists, and other creators of things, even those of us who may not naturally have the gift of the gab.
The following is a guide to writing style. In most cases, we write documentation using some form of Markdown syntax. However, the syntax used is less important than the style imparted.
Read the instructions
Before even considering style, when completing an exercise where you have been given instructions, please start by reading the instructions.
For example, if told to “replace the contents of this file” with something else, do that!
Note what you have been asked to do.
If you needed me to tell you this, I’m not sure reading this will help you. But I write it anyway as a form of liability protection in case someone inevitably claims that they didn’t know they were expected to follow the instructions.
Always check your work
Once you believe you have completed your work, compare your work again to the instructions as form of basic quality asssurance.
If your work involves sharing or publishing something, make sure the shared or published version is correct.
For example, if you replaced the contents of a file on your own computer according to the instructions, saved it nicely on your own computer, but the version of it you were asked to publish online does not match the version you have on your own computer, then you have not completed your work.
Note what you have been asked to do that you did not do.
Check both your own copy and the published or shared copy for correctness.
The rules of grammar still apply
Yes, you may be writing documentation of a software or data science project, not a creative writing class essay. But unless you are in an organization or environment where you can autocratically dictate your own rules (in which case you would most likely not be reading this), the rules of grammar still apply to you.
Spot the punctuation error and the questionable use of a colon.
Check your punctuation. Check your spelling. Check your subjects and objects and verb tenses and all that.
All documents must have headings
All documents must have headings, and use subheadings wherever relevant.
For example, if writing a few paragraphs about an article you found interesting, give your document a heading so others can clearly identify the topic and purpose of your writing.
No heading. Typos.
Even a generic heading like “Interesting Article” would be better than nothing for a document about an interesting article.
Use headings meaningfully
Do not use headings/subheadings for things that are not headings. Use top-level headings to indicate the top-most title of the document. Use second-level headings to begin sub-sections of that document.
A sub-heading must have some regular text or imagery within it. All major writing style guides will require this, e.g. APA style.
For example, if writing a few paragraphs about an article you found interesting, give your document only needs one single top-level heading clearly identifying the topic and purpose of your writing.
Three levels of headings of dubious value and a poorly-worded link before getting to the point. The document would also benefit from a second level heading above the last paragraph, which is conceptually a separate section of the document.
For a document with no sub-sections, a single top-level heading would suffice.
Use headings in order
Never jump from a top-level heading to a third- or fourth-level heading. This would throw the information structure into disarray. And do not use headings of a specific level for how they look. Rather, use them for what they conceptually indicate.
This basic document organization principle is found in all major style guides, e.g. APA Formatting and Style Guide.
An unexplained jump from top-level to third-level heading.
Never put links in headings
In general, it’s best not to make document headings into links. There’s some debate about this among the chattering class. But avoiding this is best.
If a heading serves a double-duty as a link, this fact may not be clear to the reader. Better to place a link separately in the text below the heading.
Is this a heading or is this a link?
Never put colons at the end of a heading
A colon (:) indicates something to follow. A heading also indicates something to follow. Thus, a colon at the end of a heading is redundant and poor style.
The University of Sussex has a nice guide to colon usage, which states:
You should not use a colon, or any other mark, at the end of a heading which introduces a new section of a document: look at the chapter headings and section headings in the present document. It is, however, usual to use a colon after a word, phrase or sentence in the middle of a text which introduces some following material which is set off in the middle of the page. There are three consecutive examples of this just above, in the second, third and fourth paragraphs of this section.
We agree.
A redundant colon at the end of a second-level heading. Also note that a single raw link URL is not deserving of its own sub-section of the document. And note the quotes around the expression, “coding getting better”… this seems unecessary, as this term is not an idiomatic expression or a direct quotation.
Avoid shouting in headings
Nielson usability research has found:
Reading speed is reduced by 10% and users are put off by the appearance of shouting [in all caps].
Most authorities on typography and design would agree.
A heading written in all capital letters.
Use lists for lists
When writing a list of items, use a list format. Do not simply write the list of items in a single line, and do not simply write the items each on their own line. Use a standard list format such as bulletted or numbered lists.
An example of a list with poor formatting:
The same text, better formatted:
Avoid writing like an AI robot
Best to avoid using icons in document headings, subheadings, and lists. This and other overused decorative writing styles are beginning to be considered hallmarks of AI-generated writing style, which many are now shunning.
If you’re going to use large language models to write something you were supposed to write yourself, at least put some effort into making that less glaringly obvious.
Identifiably AI-generated writing style.
PS, even though imperfect, it’s also best to run your text through an AI detector like Quillbot to see whether others will consider it GPT-ish, even if you wrote it yourself.
Use meaningful link text
If linking to something, make the visible text easy-to-understand so a viewer knows what it is that is being linked to.
The W3C accessibility standards require this, but it’s also common sense.
Meaningless link text. It does not help us understand which article is being linked. Also note the incorrect description of the content in the heading text: this section does not contain the article, only a link to it.
Avoid raw link URLs
Make each link show a meaningful description of what it links to. This document explains well why using clear link wording is important.
Also note that the “This document” link text in the previous sentence explains nothing about what you will see after clicking the link. In other words, it’s relatively meaningless link text. Do better.
Link text consisting of a raw URL. Also note the colon in the heading and the unnecessary heading text redundantly describing that which is obvious.
Note that some formal citation guides require you to include the raw URL of an online source.
Consider formal citation styles
While not a hard requirement in all cases, when referencing an existing work, or citing from a source, consider providing more than just a link to the source. Most readers would benefit from also knowing the author, title, and possibly the publisher and date, regardless of whether you adhere to a specific citation standard or not.
An example of an idiosyncratic reference style. Doing it your own way is better than nothing.
NYU Libraries’ guide to citations contains links to examples of how cite works according to the rules of various popular English language style guides, including APA, MLA, and others.
Columbia College’s “How do I cite?” tool allows you to select the source material type and see multiple examples of citations that follow the APA style.
Publish in an appropriate format
When sharing or publishing your writing, do so in a format that is most usable for your intended audience and most suitable for your publishing medium of choice.
For example, when sending a personal message to a friend via email, don’t write the message in Microsoft Word and then send the Word-specific file (.docx) as an attachment the email. And don’t write the letter in Google Docs and then send your friend the link to that Google Doc in an email. Rather, write the message as text in the body of the email itself. This way, your friend can receive the email and immediately read the letter.
Similarly, when publishing a document to the web, don’t publish it as a Microsoft Word, a PDF file, or a screenshot of the text, unless you have good reason for doing so. Rather, publish it in a format that is immediately viewable in a web browser, such as using regular web page HTML code. This allows a viewer to immediately read the document and perform other actions upon it using basic web browser functionality, such as copying or searching the text.
If sharing a structured message or short document with others via a team messenger app, such as Discord, Slack, or Microsoft Teams, use the formatting abilities of the messenger app itself, rather than writing the document in a separate application and then attaching it or linking to it in the messenger app. Most team messenger apps support Markdown syntax for formatting.