knowledgeDoc

Writing creatively for documentation projects

Richard Kennedy
by Ricahrd Kennedy

Technical documentation must always be accurate and easy-to-understand. This means using unambiguous terms, avoiding long sentences, and enabling users to easily find information. This can sound a bit dry, but crafting good documentation requires a creative mindset during each project phase.

In my last article I discussed how creativity is essential in the planning phase of a documentation project. In this article I will look at the writing phase and discuss the role creativity can play in the creation of superb technical communication.

It's not just writing

Firstly, it’s important to realise that technical communication is not just writing. Every piece of documentation is a combination of textual and graphical elements. Increasingly, these elements are being prepared for mobile and web devices as our clients seek to present the most modern and visually appealing documentation possible.

During the writing phase of a documentation project a technical writer will:

  • write, edit and proofread content
  • capture and edit digital images
  • design diagrams
  • design logos.

Let’s briefly discuss how creativity can be employed in each of these areas to achieve great results for clients.

Writing content

The general rule of technical writing is to ensure sentences are written clearly and consistently. Since most technical documentation is procedural, this often means writing passages such as:

  1. Click the Firefox shortcut on the desktop.
  2. Select Tools > Downloads from the main menu.
    The Library window is displayed.

Being creative means constantly looking for ways to improve documentation and being aware that words aren't always the best mode of communication. This documentation is fine, but it can be enhanced further by replacing the text "Firefox shortcut" with an image of the shortcut and including a tip describing the shortcut (shift+J).

Also, although sentences should generally be structured with a leading verb ("Click the…", "Select the…"), this isn’t always the case. Know the rules so that, like an artist, you can know when to break them.

Capturing and editing digital images

One of the most common tasks of documentation projects is taking screen captures to illustrate features such as buttons in a software program or links on a webpage. This is a routine task that shouldn't be overcomplicated, but when you are taking the capture you should think creatively about improving the appearance of the capture.

  • Is it cluttered with extra information that doesn’t help the reader?
  • Could it benefit from a highlight box to draw attention to the feature being documented?
  • Is there white space in the document that could be removed to improve the clarity of the capture?

Tip: Cutting down a capture can also save time when publishing print or PDF documents by ensuring that captures are small enough to fit on the page.

Designing diagrams

Sometimes it is difficult to explain concepts using only words. For example, inserting a new employee into a human resources database might require a profile to be created in a general community database, which then results in certain details being applied to similar records in payroll and staff databases.

In such cases it is useful to create a diagram that demonstrates how the sections relate to one another. The creative aspect of this task is two-fold.

Firstly, you need to be aware of concepts that are complicated and would benefit from a diagram. Secondly, you should carefully consider the actual appearance of the diagram.

  • Does the diagram clearly illustrate all steps in the taskflow?
  • Are there additional stylistic considerations for the diagram?

For example, if the company has a signature colour such as Coca Cola red, you might apply that colour to the boxes in the diagram.

Designing logos

Every company and most products have logos. Imagine a client supplies their logo in as a small bitmap file for the cover of an A4 document. Drawing on my graphic design knowledge I know that this is a problem because these graphics will pixelate when published at a larger size.

Creativity in this instance is recognising the problem and then drawing on existing knowledge to create a solution.

Sure, I could simply ask for a bigger larger file and twiddle my thumbs, but why wait? I know what the problem is and it’s easy to create a solution in minutes using a vector image program such as Adobe Illustrator. Now I have a logo that can be recreated in any size.

At the heart of writing creatively for technical documentation is being excited about the skills you can leverage to create great results for clients. These tips are just the beginning and I would encourage technical writers worldwide to continuously explore new technologies and consider how they can improve their documentation.

Back to blog home.