A reference guide is a detailed reference of some particular part of software. It is a more advanced version of a user guide, which is created for users, who are familiar with the software but need some details or quick guidance regarding certain aspects of a product. Therefore, there are particular requirements which are crucial for this kind of a guide. So, I have researched and identified the top 5 tips that will guide you through the process of creating an efficient reference manual.

1. Make it searchable

The main characteristic which makes this end-user document special is excellent searchability. Indeed, referring to this document the reader expects to quickly find what he/she is keeping an eye out for. The best solution for this is to make an index where all the articles are put in alphabetical order and are easy to find.

2. Make it stand-alone material

Every article in a reference manual should be an independent document, which can be understood without reading the whole guide. This means, you can read a reference guide in any order and it won’t affect your comprehension. So, choose the right format (functional manual or procedural guide) depending on what you want to explain and make it stand-alone help material.

3. Make it detailed

A reference guide is aimed at advanced readers, who it is assumed already know the main concepts. That is why all kinds of details are highly welcomed. So, while describing different processes and functionalities of software don’t be afraid to dive deeply into a world of additional facts.

4. Annotate the visuals

The main focus of a reference guide is to put visuals, in most cases screenshots. They are considered to be truly useful elements, because the best way to explain product interface is to show it. As it was already mentioned, reference guides tend to be detailed, so visuals are also expected to contain as many details as possible. That is why you have to spend some time annotating your screenshots and afterwards complement them with short and up-to-a-point descriptions.

A quick reference card as a part of a reference guide, created with the help of content development tool StepShot

A great solution would be to use a specific screenshot capturing tool to save time and complete the task effectively. One example is StepShot. As it is demonstrated on the image above, you may first take a set of screenshots and afterwards annotate them using a wide range of editing tools. As a result, you will get a reference guide consisting of separate reference cards on various subjects.

5. Be accurate

Along with being detailed, a reference guide also needs to be precise. Make sure, the information you included is relevant and is kept up to date.

On the top of that, the terminology you use in a reference guide should be especially accurate. By this, I mean you need to determine the vocabulary for the guide and use one term for one feature, without using any synonyms and similar terms. Otherwise, a user might get confused and, as a result, not find your user document advantageous.

To sum up, similarly to all other types of user guides, a reference guide is the most efficient when created in accordance with particular requirements and rules. They are not hard to follow and we hope you have already tried them out and have found some value. So, we definitely encourage you to look for the best practices before starting your work on different types of  documents. If there are some other tips and tricks we didn’t mention in the article, we would appreciate your comments below.

– Content Marketing Manager
Passionate about making the process of software documentation for IT professionals smooth and painless 🙂
SHARES