When it comes to tidying up the first name that comes to our minds is Marie Kondo, professional organising consultant and author of the international bestseller ‘The life-changing magic of tidying up: the Japanese art of decluttering and organizing’.

We always talk about decluttering and organising in our everyday conversations here in Editha, but unlike the KonMari method, keeping only those things that spark joy doesn’t seem an applicable criterion to technical documentation.

We all have a drawer in the kitchen full of ‘random stuff’. Nobody knows how it is possible that there are dead batteries and expired soy sauce sachets in there, however, only the idea of tidying up that mess and put everything in its right place is enough to make us close it with a bump of our hip.

The same thing often happens to company documentation. We end up with so much content saved everywhere: copies of copies of reviewed files – that differ only by one or two words here and there – and documents scattered across at least three different software applications. Reorganising it seems to be a mission impossible to dump on whoever will come after us, who will leave files open after making a few more backup copies of them.

Where to start?

A place for everything and everything in its place. The first step for tidying up a document is to arrange each piece of content consistently so that it can be easily found, updated and re-used later for the creation of new documentation. Not sure where to start?

According to our working method, the most efficient way to organise information is to split it into different stand-alone topics, that is meaningful text units that do not depend on other text blocks. Moreover, it is important to use the same structure for all topics. For example, each introductory section should always contain the same sequence of information, so that the end user knows what to expect and how to read all the document sections.

Speaking of sequences, if contents include activities to be carried out in a specific order, arrange them in chronological order, without taking for granted that the reader knows that an action must be performed before starting another one.

Once topics are positioned one after the other to create the final document, the text structure should clearly reflect the hierarchy of information. Main information should appear first, and secondary information should follow.

Appearance matters too

In our article on accessibility in technical writing, we have already focused on the fact that not all texts can be read by the human eye. Therefore, screen readers must be taken into account when we deal with text writing and its final layout, without penalising visual organisation though.

Tables, images, fonts, titles, styles and colours should be functional rather than beautiful (let’s leave WordArt and ClipArt in the past). Always keep in mind that decorative elements just for the sake of them do not add any value to technical documents. Thus, we should focus, instead, on a page layout that makes reading enjoyable without jeopardising the understanding of the text nor that of the instructions.

The choice of graphics must be, in any case, coherent with the documentation – images that are purely decorative and do not add any relevant information to the text should be avoided.

Icons and symbols must be used consistently in compliance with the international guidelines for their safe, efficient and effective use. Always use the same symbol and the same colour according to the type of information to be displayed.

Where did I put it?

One of the main aims of reorganising contents is to boost the chance of re-using existing contents to ensure consistency throughout the documents and avoid duplicates. After tidying up contents, it is crucial to rely on a search and indexing systems that prevent chaos to reign again.

Therefore, it is important to organise documentation with a searchable structure, possibly with a table of contents in case of a printed document, to allow the user to easily browse multimedia content or the Web.

The index should be complete and consistent – it is important to keep in mind how the topic structure in the manual could impact on the user search. For example, even though ‘error lights on’ may be significant as a title, the end user is more likely to search for a shorter sentence, such as the name of the section ‘Lights’.

Internal references within the document, such as references to the chapters or links and cross-references in multimedia content are essential to help users manage all that amount of information.

Even graphics within the document, which are often forgotten in a multitude of texts, should be searchable by name or caption.

Therefore, organising the documentation by topic, in a clear way, is useful both to the author and to the end user. The author will be able to check that nothing important has been left out in the documentation and that it meets the usability and readability requirements, and the user will benefit from it.

In search of joy

If reading this post you immediately thought about your drawer of shame, and your booklets, manuals and instructions no longer spark joy, the time has come to tidy up your documentation. We can guide you in this activity step by step, from the analysis of your existing contents to the recommendation of the right software application or CCMS for your company. Just drop us an email.

© Editha S.r.l. – This post and its content are copyright of © Editha S.r.l. 2022. All rights reserved.