Writing tips

Writing tips for technical documents

Are you writing a technical or scientific document? Use these ten writing tips to create well-structured and easy to understand documents.

To write a document that readers will find interesting, clear and useful, you need to think about the whole document from the very beginning.

These writing tips can help you get started.

1. Do an audience analysis

For whom are you writing? This is a fundamental question that will determine how you will write the document and you need to resolve this first.

If you have a known audience (e.g. a user group), the best way to find the answer to this question is to go and talk to the audience. If that is not possible, then you could brainstorm for possible answers with the people involved in writing the document.

2. Do a purpose analysis

What is the purpose of your document? This is another fundamental question that will need to be resolved before you can start writing.

Try to identify the purpose of your document clearly and work out what you would like to achieve with it. If you are writing a manual, what will it explain and which problems do you hope to avoid by giving readers (i.e. users) this information? If you are writing a scientific report, what would you like your readers to find out and remember?

3. Plan the document structure

Spend time developing your document structure. This will help you during the writing process.

Use the answers found in writing tips 1 and 2 to develop your structure. A preset structure will show you where best to discuss certain topics and also give you a sense of direction while you write.

However, this preset structure should not be too ‘rigid’: adjust it during the writing process if you think it does not work quite as well as you planned. This tip is as important as the next, so always apply these two writing tips together.

4. Make your document structure logical

If readers understand your document structure quickly, they will also quickly find the things they are interested in. This will make them happy and they will find your document useful.

The logic in the structure of your document is therefore very important. Structure can be chronological; historical; methodological; action, process or place-driven; or may adhere to a set standard (e.g. a procedure).

Whichever structure you adopt, make sure it is reflected in the headings and subheadings. If these headings clearly communicate your document’s structure, readers will find the information they want much faster.

See also formatting tips.

5. Write in a direct manner

By communicating directly with your readers, they are more likely to listen.

For example:

  • If you are writing an instruction document, such as a manual, you could address the reader as ‘you’.
  • If you are writing a report or descriptive document, try to use the active voice as much as possible.

See also editing tips.

6. Write for a broad audience

Scientific or technical documents are often directed to a very limited and often specialist audience. This can be appropriate, but in many cases it can restrict the usefulness of the document or turn readers away.

Even scientific and technical documents can benefit from being written for a broad range of readers.

Widening your audience can be beneficial in many ways, especially if the documents are grant proposals, journal articles, reports, manuals, etc.

7. Explain terms and jargon

As in writing tip 6, missing explanations of terminology and jargon can turn readers away.

Try to include the readers that may not be at your level of specialty by providing definitions of terms and jargon words.

These explanations do not need to clutter the main text, but can be provided in stand-alone boxed text, glossary lists, footnotes, appendixes or even in a dedicated ‘background’ section of the document.

See also editing tips.

8. Standardise the peripheral components

Peripheral components of your document include:

  • the objects that you insert to illustrate or clarify the text (e.g. tables, graphs, diagrams, images or icons)
  • text presentation aids (e.g. citations, references, footnotes, captions, acronyms and abbreviations, headings and subheadings, lists and quotations, tips, notes and warnings)
  • layout (e.g. page design and graphic layout, headers and footers, page numbers).

If you make these components consistent throughout your document, the readers will learn quickly, find information faster and can focus on the really important messages in your document.

9. Keep track of all sources you use

As a writer, you will invest many research hours into your technical or scientific document. You will most likely rely on the work of others and refer to it.

While writing, update the list of sources you use simultaneously. It will save time at the revision stage and will ensure you do not accidentally omit important cross-references.

Most importantly, do not plagiarise. Acknowledge all sources and obtain the required permissions from the authors.

10. Get help or feedback

After completing a first draft, edit your own writing, using these editing tips as a guide.

However, do not try and manage the writing process on your own. You will save time and effort if you ask a colleague or editor to help you through the writing process.

A professional editor can help and guide you from the beginning of the writing process. They can also give a reader’s perspective on your document and revise the drafts as you write.

Your suggestions are welcome

These are my top-ten writing tips for technical and scientific documents. If you have any comments or questions, or would like to suggest further content, please leave a comment below.

To find other recommended resources for writers and editors, check the resources page.

 

☙ ❧

Leave a Reply

Your email address will not be published. Required fields are marked *