The why, who, and when of documentation

Whenever you want to tell something to anyone, for instance when considering to start writing documentation – start considering why you want to do it?

Who will hear it or read it, and when does it happen – in which situations are they?

Every question has its own answer

You will quickly gather a list of different needs – different questions to be answered by the documentation:

  • What is this product – what can it do? This may be asked before the customer has bought it, or maybe an employee is being asked to start using this product and would like to know what it does.
  • Which requirements does the product have? Before using it, it may need installation – which requires an installation environment of some kind to be established. And it may have ongoing requirements too, such as the need for a worker to monitor it or some fuel to be added.
  • How should the product be maintained? Does it need lubrication, software updates, regular supply of tear and wear parts?
  • How is the process for using this product meant to be? Quite often, a product has its own needs for things to be done in a certain order – even though using the product also should fit into a general workflow.
  • How do I get started? As a new product can look overwhelming at first, some guidelines on what to do first will often be needed or at least appreciated!
  • How do I perform this or that specific task? A use case oriented approach to manuals and guidelines are often needed – the user simply needs to perform a task as fast as possible but does not know exactly what all the steps would be.
  • What more is there – how can I get the maximum benefit of the product? Additional reference and background information may help users get to that point where the product is no longer a time-consuming extra but, indeed, a means to save time and become more productive.

There could be other questions, depending on which product we are talking about. And often you would consider writing guidelines on how to do something that may involve this particular product but also other products and general work steps. This can be highly useful for the user and allow for your product to be valued higher, as it is seen as a piece of the puzzle of a complex work that will then more easily be completed.

Analysis

You know what you want – a manual or some other technical documentation. Or some business documentation, such as a business plan. But why do you want exactly this? And which shape should it have? How many documents – just one? Or perhaps several, each dedicated to a specific purpose or a specific group of users?

Analysis always pays off! It allows for the project or activity to take a proper direction already from the start. Of course, this should not prevent anyone from getting wiser along the way, maybe reconsidering what is needed or deciding to add something more. Therefore, analysis is in general not a one-time up-front phaenomena, it is an activity that takes place in parallel with the rest of the activities all the way to the end.

At times it makes sense to create a separate analysis report before doing anything else. This can help make the best decision on how to proceed and may be needed for your internal processes around this. At other times the analysis should rather be focused on a series of meetings, perhaps arranges in a formal setup of some kind, e.g. agile, that allows for stakeholders to be informed along the way and for the course to be changed.

Even the smallest tasks usually benefits form some sort of analysis – be it perhaps just a brief meeting to introduce the participants to the task, thereby finding out of anything needs to be determined.

Various types of documents

We could easily name a zillion different types of documents and other documentation shapes and approaches, but instead we wish to point out that the ways of arranging documentation are almost endless. The traditional printed manual or installation guide may still go strong, but various other and additional traditions have appeared – not the least guidelines for upgrades of software and management of waste, depending on product type, which were not needed just a few years ago but are demanded by customers or by law today.

Think creatively about the matter – what information will be needed by a customer, a user, a recycling station, etc. – right now, when beginning to use the product, during normal use, at the end of the product’s lifetime – and later?

Also consider who the users of the information are and how their backgrounds and knowledge may look like. Maybe set a divider line for the expected knowledge of these users, to avoid trying to document the whole world again and again. And consider a layered documentation where each user can jump in at the layer that corresponds to their individual knowledge, skills, and needs.

And during the proces, consider where this information can be found today. Does it already exist somewhere so that the considered users should just be pointed into the right direction? Is it based on inside knowledge that may not currently be available in any shape and perhaps will require some analysis of the product itself – or is it available, just needs to be put in a user friendly way?

Some documentation may be about the product but without describing the technical construction or use of it – this could be legal matters or environmental information, and probably a lot more, and this information may be available from different sources, so it should be considered to which extend they are available.

Various media

Paper document

The Software Craftsman bookStatistical Analysis bookPCB Currents bookEven though the paperless office was announced many years ago we still rely on printed matters. A recent survey in Sweden revealed that a majority of people still prefer to read books on paper. There is a difference based on age but all ages have their large share of people preferring paper books.

When considering the special case of documentation, the books may not be used in the same way as, say, a novel – it is not being read from end to end, not read in the same places as the novel, such as the airplane, the train, or in bed. But often you wish to keep a book open next to you, describing the steps that you then may carry out on your computer. Or you use the book during a study, carrying it around with you, making marks in it, lending it out to others…

Shorter paperwork includes a product sheet to be handed out at exhibitions and the like, brochures to pile up on the front desk for inspiring your visitors, and posters to hang on the wall with overviews and instructions. And there are many more.

We should not print everything just because it is possible, but often it has a benefit to some people in some situations, and then it should be considered. When designing a document, it is then a good idea to design it for looking good on print.

Electronic document

Volatile MarketsBrand Revitalization bookFoundations of Green IT bookApart from simply being a file containing the same document as the one that we also have in print, the electronic format allows for many other shapes and constructions. Not the least, it can contain hyperlinks – to different parts of the same document or reaching out to other documents or even websites or applications. From an electronic document you can then actually do the work; it becomes an active document.

Certain file formats are more popular, and pdf is by far the most used for published documents. It can allow for various clever details and features such as making notes, signing, showing a table of contents, etc., or it can be a simple “print” (in fact, this is the origin of the pdf format – a postscript file to be printed). Word formats, new or old, are quite popular too, and Excel files as well, along with PowerPoint. Various similar formats are used by competitors to the Microsoft Office, but often it confuses people to distribute files in these formats, so if not pdf, then often one of the Word, Excel, or PowerPoint file types should be first considered.

The electronic documents have the huge advantage that they can be updated at any time and made available as downloads – this simplifies the distribution process compared to the one for paper documents. Also, you can distribute the documentation files with the software files, if you wish.

Website

As a way to gather and share freeform documentation, a standard website may be suitable. It can be dedicated for the purpose or simply be a page at your existing company website.

Knowledge base

In order to handle a large amount of individual descriptions, like in an encyclopedia, and adding the search and link features that computers perform so well, a knowledge base system of some kind will often be suitable. A well known type is the wiki. Everybody knows Wikipedia but actually it is easy to create a similar system for a specific purpose, either for internal use in the company or for sharing, for instance, documentation with your customers.

We have made an example wiki:

Inidox Documentation Wiki

Other approaches

Apart from publishing a document of one shape or another through one or another kind of media, there are other ways of providing the same new knowledge and ongoing support to the users. These ways are by no means new but thinking them into a documentation approach may be new and ground-breaking to some. However, it may suit the situation and therefore be a useful element of the total solution.

Courses

You can tell the user of a product how to use it through a manual, but you can also demonstrate it while still giving background information and showing related products and how it all works together.

A good old training course is in general the way to go if many threads of knowledge need to be wowen into a carpet of skills and knowledge, and it may be arranged more or less as a workshop in order to give hands-on experience with the product.

Seminars and webinars

In comparison with a course, a seminar (or a webinar, if it is conveniently attended through a web browser or the like) usually has more of an explanatory nature, less hands-on. And often information will be given on more what the product is and which features it has rather than exactly how these are to be used.

However, the line between these approaches is not fixed.

Online videos

Courses, seminars, and webinars can be recorded and offered as online videos, but you can also make dedicated videos that explain one particular detail of the product or its use, without trying to embrace the full product. These small videos have become immensely popular during recent years, not the least thanks to services like YouTube that make the videos easily accessible to anyone.

Of course, videos do not need to be available online but can also be provided on a DVD or whatever, but if your product has many users spread around the globe, then you shouls at least consider if videos of any kind could help them use the product better.

Technical support

It is not uncommon today to deliver products completely without any kind of printed documentation or perhaps just with a brief “getting started” guide and then offer access to a support function through email, phone, or web forms. This way the technical support becomes the main source of information for many users, supplemented with unofficial support information provided by other users as books, web fora, or whatever.

No matter what else is delivered to the users, consider how such a support function may supplement it.

Advertisements

Advertising is often seen as a kind of sales tool – you cannot trust the copy in the advert as it is simple meant for catching the potential customers’ attention, not for teaching them anything. But it doesn’t have to be this way (only) as practical information given in ads may in fact demonstrate your will as a manufacturer to met the customers where they are, helping them out with their needs, inspiring them to the best use of your product.

This could help selling and at the same time take off some of the load from the technical support, as well as reduce the need for other types of documentation.

Inspiration from other people: reviews, talking to neighbors

You may wish to actively seek to make users describe their experiences with your product on their blogs or to their neighbors, colleagues, etc., perhaps through some kind of incentive. Quite many users of technical products prefer getting assistance from someone they know rather than from a big manual, a confusing FAQ, a frustrated technical supporter, or whatever they see as the alternatives. And users may trust other users so much that they are willing to spend more time on listening to their explanations than they are willing to spend on your own documentation products.

Users groups, dedicated magazines (if your poduct has a sufficiently large users base), newsgroups, fora, and other concepts can be established with users taking part as your partners.

It is worth considering how this kind of “crowd sourcing” of tecnical assistance can be established and maintained, and how you can take part in it and assist it with the right documents, videos, etc. to give the users the impression of taking part in a great community around your product.