Unlocking the Power of Effective Documentation
Good documentation for a product is like a well-written rulebook in a boardgame - it makes the game easy to understand, enjoyable to play, and accessible to all.
Root is a strategy board game that took the tabletop world by storm upon its release in 2018. Developed by Cole Wehrle and published by Leder Games, Root is a game of woodland might and right that pits players against each other in a battle for control over a richly detailed and immersive woodland kingdom. With its unique asymmetric gameplay, gorgeous artwork, and rich thematic setting, Root offers endless hours of fun and strategic challenge for players of all skill levels. Whether you're a seasoned tabletop enthusiast or a newcomer to the world of board games, Root is sure to captivate your imagination and test your strategic abilities to their limits. Although Root is a complex game with a rating of 3.78/5, a well-designed rulebook makes it easier to learn and start playing. For more information, please visit: BoardGameGeek
Introduction
While a board game may be well-designed and not overly complex, it can be difficult to understand and enjoy without a good rulebook. Developers often focus on writing efficient, high-quality code that meets the requirements of the project. However, the importance of good documentation is sometimes overlooked. Good documentation is an essential component of any product, as it provides a roadmap for users to effectively understand and use it.
Recently, I had a discussion with a colleague about improving the technical documentation for our project, and he suggested checking out divio. The website, written by Daniele Procida, is based on The Grand Unified Theory of Documentation by David Laing, a popular and transformative documentation authoring framework. I have read the websites' articles and watched a YouTube video presented by Daniele. In this blog post, I will provide a summary of the suggested framework, as well as share my personal experience about effective documentation.
It doesn’t matter how good your product is, because if its documentation is not good enough, people will not use it.
documentation.divio.com
According to the Grand Unified Theory of Documentation framework, there are four distinct components of documentation, rather than one monolithic entity:
- Tutorials
- How-to guide
- Reference materials
- Discussions
By recognizing and addressing each of these components separately, we can create more effective and targeted documentation that meets the needs of both authors and readers.
Tutorials
Tutorials are instructional lessons that guide readers through a series of steps to complete a project. They are designed to teach how to do something, rather than just to provide information. As a product owner, it is important to ensure that the end goal of the tutorial is both meaningful and achievable for a beginner user. A well-designed tutorial can help learners make sense of the product, while a poorly executed or missing tutorial can hinder the acquisition of new users. Writing and maintaining tutorials can be time-consuming, but they are essential for helping users to successfully navigate and utilize a project.
The list below shows the main points of tutorial documents:
- Writing should be clear and easy to understand for the reader.
- Provide a hands-on experience that inspires the reader.
- Start with simple concepts and gradually move towards more complex ones.
- Make the document enjoyable to read. Avoid starting with complex information that may discourage the reader.
- Learning by doing should be emphasized throughout the tutorial.
- Ensure the tutorial is repeatable on all platforms, even if it requires more work.
- Use concrete examples and specifics rather than generalizations.
- The tutorial should focus on practical skills.
- Avoid distractions and unnecessary options.
- Emphasize the importance of the tutorial for those who are new to the project.
- Demonstrate to newcomers that it is possible to learn and that the tutorial is oriented towards learning.
How-to guide
The purpose of how-to guides is to provide a step-by-step process for solving real-world problems. They are goal-oriented and provide specific instructions for achieving a particular outcome. For example, how to setup your company VPN, or how to add a new SSH key. Unlike tutorials, how-to guides assume some level of prior knowledge and experience from the user. While tutorials are designed for beginners and cover basic concepts, how-to guides are intended to answer more advanced questions. In the realm of software documentation, how-to guides are typically well-executed and enjoyable to write.
Based on a project experience, how-to guides are sometimes also called
runbooks. Each runbook has a specific goal and provides readers with step-by-step guidance to achieve that goal.
The following list outlines the key points covered in the tutorial documents:
- How-to documentation is problem-oriented.
- It focuses on achieving a specific result through a step-by-step guide.
- How-to guides are entirely practical.
- They are easy to write for technical/product owners.
- Readers should have some basic knowledge before starting the guide.
- How-to documents can be linked together. Therefore, if one document depends on another, readers can easily navigate between them.
- Choose an appropriate title for the guide.
Reference materials
Reference guides provide technical descriptions of machinery and how to operate it. Unlike how-to guides, reference material focuses solely on information, providing details about functions, fields, attributes, and methods. It may include basic descriptions of how to use the machinery, but it should not attempt to explain basic concepts or provide instructions on how to achieve common tasks. Reference material is straightforward and austere, and may be generated automatically to some extent, but it is never sufficient on its own. For some developers, reference guides are the only kind of documentation they can imagine, assuming that others only need technical information about the software.
We use references every day! API references, Linux commands' references, Python packages'references, and more.
Discussions
Discussions or explanations in documentation clarify and broaden the coverage of a particular topic, providing a higher-level perspective and illuminating the subject matter. Unlike how-to guides or reference material, explanations are understanding-oriented and discursive in nature, often scattered among other sections rather than explicitly created. Discussions can be challenging to create as they require a broader view of the software and a deeper understanding of the subject matter. The division of topics for discussion can sometimes be arbitrary, defined by what the author thinks is a reasonable area to cover at one time rather than a specific task or learning objective.
Example
Several websites offer their product documentation using this framework. Let's take a look at one of them: Ubuntu Server documentation!
As we can see, the documentation includes the four main components:
Ubuntu Server tutorials: This section of the documentation contains step-by-step tutorials to outline what Ubuntu Server is capable of while helping readers achieve specific aims. The tutorials start with a basic installation guide and continue with a collection of related tutorials and topics that will help readers learn more about Ubuntu Server.
Ubuntu Server how-to guides: The documentation includes a variety of how-to guides that provide readers with specific goals to accomplish. However, it is assumed that readers are already familiar with Ubuntu Server, as the guides may require readers to understand and adapt the steps to fit their specific requirements. While the guides will help readers achieve an end result, they may need to be customized to fit specific needs.
Ubuntu Server explanation guides: This section includes explanatory and conceptual materials aimed at enhancing user comprehension of the functioning and configuration of Ubuntu Server, thereby making it easier to use. The section is divided into three main topics: Software, Network, and Cryptography.
Ubuntu Server reference: This section provides a list of available software and command references. Readers can refer to this documentation to figure out how to interact with different Ubuntu tools and commands.
Summary
Based on the the Grand Unified Theory of Documentation framework, the four distinct components of documentation are interconnected. Tutorials and Discussions are particularly helpful for readers who are just starting to learn, while How-to guides and references are more practical documents that assist in development.
For a software development project, a README file is an essential component, as it serves as a guide to help users understand what the project is about and how to use it. A well-written README file can ensure that a project is more accessible, easier to use, and encourages collaboration among developers. Let's discuss README files in another blog post. ;)