Technical Writing

Technical writing covers the process of writing documentation, wiki pages, guides, and introductions (including project READMEs). It does not cover scientific repot writing.

Useful resources:

• Google technical writing course
• Rules for writing tutorials

For a more in-depth approach to documentation writing, see Diataxis

Audience

Writing should always match the audience. Therefore, the first thing you should do is to define your audience’s:

• role
• existing knowledge
• abilities
• proximity to the knowledge you’re writing down

Then, you need to identify exactly what you want the audience to learn, or what tasks they should be able to perform.

This will help you to structure your writing, and ensure you have something to check against as you progress.

Other tips:

• avoid idioms and cultural or sporting references
• avoid complex or rare words where possible
• when editing, try to read from the perspective of your audience, taking on multiple roles

Layout

First, how much knowledge are you trying to put down? Which of the following formats is most suitable:

• a single document
• multiple linked pages, like a wiki
• an ordered list of documents to go through in order

Start with a structured, high-level outline to group topics and clarify the order of presentation. Using this, ensure you introduce information in a logical, coherent narrative, when it is most relevant to the reader.

Also consider what the audience wants to learn. If you’re writing an introduction to an SDK, put a quick-start guide before more complex code. If you’re writing a literature review, write an introduction to your topic first.

Then, you should write the scope of the document, clarifying what it covers, and importantly what it does not. It should also include what the target audience is, and what they should already know.

The introduction should state what the audience will learn or gain after reading the document.

During the document, you should try to alternate between explanations and examples.

You should also include comparisons and contrasts between your ideas and those the audience already understands.

Style

Some style tips:

• Prefer the active voice
• Use the most specific verb available, e.g. ‘raises’ instead of ‘occurs’, ‘generates’ instead of ‘causes’
• Don’t use ‘there is/are’ at the start of sentences, e.g. ‘there is a variable which stores’ → ‘a variable stores’
• Use short sentences, and focus each sentence on a single idea. You might also break sentences up into bullet points
• Introduce tables or lists with ‘following’, and end with a colon
• For lists, prefer bullet points. These should be parallel, meaning items have the same
  • number
  • capitalisation
  • category
  • punctuation
• Items in numbered lists should start with imperative verbs; they should be used as step-by-step instructions
• Write in the second person: your audience is “you”, not “we”
• If your text is code-related, use a code font, with backticks
• Try to break up large walls of text, or long series of steps.

Put some text under each heading, and avoid placing two headings directly next to each other:

## H2
### H3

is worse than

## H2
intro to topic
### H3

Jargon

The “curse of knowledge” refers to the idea that being in an expert in a topic makes you less able to explain it to newcomers.

Jargon refers to technical field-specific words (such as Hamiltonian), and also project-specific terminology. While using it may be second nature for you, your readers will likely be unfamiliar with the meaning or nuance.

If using a term for the first time in a document, define it, either by

• using/linking to an existing definition (why reinvent the wheel?)
• adding a definition in-text
• quoting a glossary

From then on, make sure to use terms consistently. Using different words for the same thing may imply subtle distinctions that you haven’t explained. This will also reduce confusion when comparing with other texts.

Another form of jargon is acronyms. The proper way to introduce an acronym is as follows:

1. full capitalised phrase in boldface
2. acronym in parentheses and boldface

From there, only use the acronym as usual. For example,

The Variational Quantum Eigensolver (VQE) is … You can also use the VQE to …

Don’t define acronyms if you’re only going to use them a few times.

Jargon can also rear its head in headings, but you should avoid this. Instead, use task-based headings. For example, ## Running QAOA is a less informative heading than ## Solving because the latter is task-based and easier to both search for and understand.

Graphics

Readers like graphics! But only informative graphics are useful. A few useful tips are as follows:

• write the caption before creating the graphic
• captions should be brief, direct readers’ focus, and explain the takeaway
• you can direct focus using red circles, arrows, or callouts
• break complex figures into multiple simpler ones
• ensure text is large and has a good contrast

Code

Code itself is the best documentation! Wherever possible, include code to demonstrate and clarify your explanations.

This code should be:

• syntactically correct
• logically correct
• as concise as possible, but no more
• clear, using well-named objects
• commented
• easy to copy-and-paste
• adherent to language-specific conventions and best practices
• continually tested
• annotated with expected outputs

Larger code blocks with comments are preferable to short snippets, because they are easier to test, and easier to reuse.

You should also inform readers of how to actually run the code you present: what libraries and versions are necessary, what API keys do you need, etc.

Try to provide a range of complexity in your sample code, right from the most basic statements, to larger complex programs.

Start simple, spiral to complexity.

Miscellaneous

When editing, you can use the following techniques to proof-read:

• read out loud
• use a screen reader
• print and use a pen or pencil
• change the font, size, and colour