As part of ongoing efforts to make LINBIT® software-defined storage (SDS) solutions better understood and more widely used, the LINSTOR® Users Guide has undergone a major change. The guide now has an introductory chapter that explains how the LINSTOR component of LINBIT SDS works and deploys storage. It also explains important concepts and terms that are used in the guide and in various LINSTOR user interfaces.
The idea behind this chapter addition is to provide LINSTOR users with a foundational understanding so that they can use the software more effectively, across a variety of environments and use cases.
Fig. 1: How LINSTOR Works
Separating Different Types of Documentation Content
Some of the information in the “Introduction to LINSTOR” chapter was already in the LINSTOR User’s Guide but spread out across various chapters and sections. By trying to collect and add to the explanatory content in a dedicated chapter, we hope that it is more easily read and understood.
This is also a part of another ongoing effort at LINBIT, that is, to conform our documentation to the Diátaxis documentation framework.
The premise of this documentation framework is intuitive: Documentation should serve its readers. However, there is not a single type of reader. In the moment, someone might be trying to tweak the configuration of an existing deployment to accommodate new storage. This person likely does not want to read background or conceptual information. This person likely just wants the commands and configuration examples that are relevant to the task at hand.
This is not the same theoretical person as someone new to the software who needs an overview of what the software can do and how it works at a conceptual level, as well as explanations of terms that might be required to work with the software.
And from this, according to the Diátaxis documentation philosophy, documentation content should be separated by using a framework of four different types of content that are based on the in-the-moment requirements of the reader.
This framework provided the motivation to better structure LINBIT documentation, including the “Introduction to LINSTOR” chapter addition.
Benefits to Existing LINSTOR Users
We hope that the “Introduction to LINSTOR” chapter is not exclusively read by new users. The chapter also includes discussions of some topics, such as LINSTOR’s object hierarchy and relationships that can be helpful reading, even for experienced users of the software.
For example, diagrams are now used, in addition to explanatory text, to illustrate the sometimes complex relationships between LINSTOR objects.
Fig. 2: The hierarchy and inheritance relationships of common LINSTOR objects
A Sophisticated Software Solution for Sophisticated Storage Problems
LINSTOR is sophisticated software and because it is open source, you can verify that for yourself. Writing about LINSTOR in a way that presents its capabilities, complexities, and nuances, not to mention its many integrations, so that they are readily understood can be challenging.
Starting the LINSTOR User’s Guide on a solid foundation is a way that we hope to engage LINSTOR users and help improve their experience when using the software.
Your feedback and participation in helping to improve LINBIT documentation is always welcome. Just like LINBIT software, such as LINSTOR and DRBD®, LINBIT user’s guides are also open source.
