What is a documentation?

What is a documentation?

Before we go deeper into the technical aspects of setting up a documentation, we first want to give you a definition of what a documentation actually is.

If you look it up on the internet you find definitions like these:

As the examples above demonstrate, documentations often are associated with technical disciplines. Many people have heard of software documentation and most of us have had the experience of following a user manual to assemble an IKEA Pax wardrobe or building something with LEGO blocks.

Even though we don’t call them documentations, we encounter them in many other areas in our professional and daily life. Best practices at work ensure quality of products and services, how-to guides help us with quick fixes, and online or in-person tutorials offer us the opportunity to acquire new skills.

So here is our definition of documentations:

A documentation comes in the form of text, illustration, video or audio and aims to explain, educate, guide or inform about topics, processes and services.

Inspired by the Diátaxis framework by Daniele Procida, we group documentations into 4 main categories:

• Explanations
• Tutorials
• How-to Guides
• References

At this point, you might ask: „What‘s the difference between those 4 categories? Isn’t it somehow all the same?“

Let us give you a clearer picture.

Explanations

Explanations are all about informing about a certain topic or process. We want to draw a bigger picture that allows the user to understand why things are the way they are. The goal is not to only present facts and theory but to encourage the user to reflect on the given subject.

Explanations don’t include

• User manuals
• Recipes
• Tutorials
• Reference sections

For example, you are currently reading an explanation about what documentations are. If you continue reading our introduction, you will learn more about content management, knowledge management and data management in the context of setting up, writing and managing any kind of documentation.

You will get an overview of different technologies, their pros and cons, and what else to consider to provide a professional user experience for users of your software and the people in charge of managing the documentation. This introduction should give you enough information to be able to think about your own documentation needs and make the right decision for your project.

Explanations can include the following elements:

• Introduction - States the purpose and previews the discussion.
• Definition - Formal definition of the concept.
• Background - Provides history and context.
• Details - Elaborates on various aspects of the concept.
• Visuals - Diagrams, illustrations, examples that clarify.
• Relationships - Connects concepts to other ideas and approaches.
• Implications - Explores effects, outcomes, and significance.
• Summary - Recaps the key points about the concept.
• Further Reading - Additional resources to learn more.

Tutorials

A tutorial, or in other words a lesson, is a learning experience that helps the user to acquire skills and knowledge. It is about guiding the user through a practical activity that sets clear expectations and delivers visible results with every step of the tutorial.

We want to familiarise the user with the tools, the language and the processes in a safe environment. This means that we eliminate the unexpected and follow a concrete and single path. We also minimise explanations because this distracts the user from doing. Instead you can provide links to “further reading”-sections.

Each user will learn different aspects by following the same tutorial. So instead of asking “What is to be learned?” we focus on the question “What is to be done?”. Along the way we establish a narrative and point out what the user should notice.

For example, instead of writing: “In this tutorial you will learn…” start with “In this tutorial we will set up an online documentation with Nuxt UI Pro and Directus CMS. Along the way we will use Tailwind CSS and set up Git versioning….”

We keep up the narrative of expectations by using phrases like: “A few moments after committing your changes to Git you will see the results on your website.”

Show the user example or actual output and improve observation skills by pointing out on the go what the user should notice. This could be for example changes in the command line or reactions of the environment.

Tutorials can be structured like this:

• Introduction/Learning goals - States what the user will accomplish in the tutorial.
• Prerequisites - Lists required knowledge/tools.
• Step-by-step instructions - Provides hands-on exercises and activities.
• Recap - Summarizes key lessons and takeaways.
• Assessment - Questions or exercises to check understanding.
• Next steps - Points to additional resources for more learning.

How-to Guides

This section is all about reaching specific goals and results. How-to guides are directed towards users who are actively at work, already have a basic understanding for the topic and are familiar with the required tools. As the users are dealing with real-world problems, we want to prepare them for the unexpected. We often find phrases like “If this…, then that.” to show alternative ways of completing particular tasks.

How-to guides help ensuring that the steps needed to reach the goal are done in the right order and nothing is omitted. Again, we don’t want to include explanations, as this distracts the user from working and decreases the readability of the guide. It should aim for efficiency and therefore only contain as little as possible and as much as necessary information for the user. For this reason, we also don’t want to annoy the user at work with introductions to tools and basics already covered in tutorials.

For example, after guiding our clients through an introduction tutorial on content management with Directus CMS we are providing them with step-by-step guides for implementing different features like image galleries or publishing automation.

How-to guides can the following elements:

• Prerequisites - Required knowledge or conditions to solve the problem.
• Intro - If needed, a more detailed description of what the guide will cover.
• Ordered steps - Sequential instructions to solve the problem, to the extent that’s possible.
• Visuals - Diagrams and illustrations supporting the steps.
• Examples - Specific use cases demonstrating the problem and solution.
• Variations - How the steps may differ under certain conditions.
• Recap - Summary of what was accomplished.
• Related links - Pointers to other related procedures.

References

Similar to explanations, reference material contains theoretical knowledge. The key distinction is that it is not used to understand a certain topic but it is consulted while the user is at work. It follows standard patterns and is written in a neutral and objective tone. Often times it contains lists of things or tables of information.

For example, users might consult a list of shortcuts while working with a software they are not yet familiar with.

References can include elements like these:

• Overviews - High-level summaries of a component’s purpose and capabilities.
• Specifications - Precise technical details of inputs, outputs, configurations, etc.
• Options - Charts comparing different options or versions.
• Parameters - Lists defining all available parameters and their usage.
• Code samples - Snippets demonstrating implementation and usage.
• Visuals - Diagrams illustrating technical concepts and relationships.

This is our approach

As you can see in our own documentation, we like to split „explanations“ into a basic introduction to have everyone on the same page and then, as a last point, go into in-depth explanations for anyone who wants to know it all.

So that‘s how we structure our documentations:

• Introduction
• Tutorials
• How-to guides
• References
• In-Depth Explanations

Of course, not every documentation needs all 5 chapters. And sometimes you might want to combine two or more of the categories into one. The important thing is to always be clear about user needs and the goal of your documentation.