Research Spotlight | All You Need is Docs | Part I

Documentation is an essential part of a software product as it provides all the necessary information to deal with it. But what exactly is this information? And who needs it? This post will guide you through the multi-faceted art of documenting software and show how it can help everyone get the best out of it. This is part one of a two-part series on the importance of documentation and how developers can better document their code and processes.

 Contributing to Dusk

Working on a complex system like the Dusk Network is no easy task. It is hard to get a complete understanding of all the components and protocols involved. Take Bitcoin as a comparison, which is the oldest and best-known blockchain network. Despite the huge number of people working on it and studying it, no single person is actually familiar with every detail of its protocol. There are two main reasons for this: on the one hand, the protocol is effectively defined by the code that implements it, which means the protocol itself is constantly changing and it’s very hard to keep track of everything; on the other hand, there is no single source of documentation. You will not find an omni-comprehensive and up-to-date document describing the whole system. Information is fragmented among pieces of code, specifications, and a myriad of blog posts and other community-based material. This can be frustrating and lead to inconsistencies in the system, and even open the door to security issues.

When I joined Dusk, the first thing I had to do was to get my head around the project. The available information was overwhelming. I could get a global idea quite easily but I easily got lost in the details. Asking around for tips and explanations was helpful but not very efficient. I felt like collecting pieces of a huge puzzle. This is no different from any other project I worked on. But I felt I had enough experience to make this whole process easier for me and for those who will join after me. So I set my mind to making this puzzle easier to assemble for everyone. This meant describing the broad picture clearly while defining all the pieces in detail and how they interlock with each other. In other words, it meant writing documentation.

While this may sound like a boring and tedious task (and, I’m not gonna lie, it can be, at moments), it also leads to a deeper understanding of the subject being described. And while the number of challenges and the amount of work to do can be daunting, it’s simply a matter of starting... like most tasks, inception is the hardest part. Once started, it's just a flow of information that funnels in as a chaotic torrent and comes out as a tidy stream... each piece of the puzzle at its place.

 

Documenting a software product

One interesting thing about software is that it’s very similar to a machine (well, it does run on a machine in the end): it’s made of different components working together in a coordinated way to perform a task. Also like a machine, it can be “dismantled” to look at all of its parts and see how it works.

Take cars as an example, whose main “task” is to move around. All cars can bring you from one place to another (if they don’t break), but they can do it faster or slower, they can be more or less safe, they can be more or less comfortable, they can be robust or break down easily. Well, the same applies to software. And when the goal of the software is to deal with financial assets, like Dusk Network, all these characteristics become of immense value. You want your car to be fast and comfortable, but also safe and robust. And so you should want your blockchain. This, in software, like in cars, needs careful designing, testing, and analysis.

Now, when you buy a car, you probably don’t care about its internal design. All you want to know is its characteristics, how to use it, and, possibly, how to customize it for your needs. In other words, what you need is an instruction manual that is as clear and complete as possible, so as to be able to harness the full potential of your car. As a software user, you probably want the same: a guide explaining its characteristics and how to use it. And this is enough for most people. But what if something breaks? Whoever is going to repair it will need more than just an instruction manual. What if you wanted to modify it, upgrade it to make it faster or safer? There you’d need something more. Documentation allows you just that.

In fact, all the information mentioned above can be described as documentation. So what actually is documentation?

What is documentation?

The truth is documentation can be different things, depending on who it is meant for. For instance, as we said, end-users don't need to know (and probably don’t want to either) the nitty-gritty details of the internal mechanics: all they want to is to use the product. So, to them, documentation is a guide explaining the main features and the available options to tune the software as they prefer.

On the other hand, developers need a much more detailed description of the product. They need to know the internal components and how they interact; they need to know the algorithms the code leverages to perform its tasks, they need to know the network protocols and technical specifications it adheres to, and they need to know the tools and libraries used in the building process. To developers, both the broad overview and tiny details are important. So, a developer-oriented documentation should include an overview of the internal design as well as the precise details of the implementation. For instance, developers might need to know the protocol specifications, like network messages and data formats, which are essential to enable different devices to communicate with each other.

This information is typically provided with the program sources (i.e., the files used to build the executable software) through a combination of “READMEs”, which are small text files describing internal components at a high level (in this context, high-level and low-level refer to the level of abstraction from the technical details), and “comments”, which are informal, human-language text in the code itself that describe functions and data structures at a low-level (hence more technically). Comments are not part of the program (in fact, they are ignored when building the application) but serve the purpose of helping other developers understand the code.

Another case is that of researchers, whose goals include formally analyzing the correctness, security, and performance of the system, as well as providing new solutions and design improvements. To them, documentation is a thorough and formal definition of the system design and protocols. This type of documentation typically comes in the form of scientific papers and specification documents. For researchers, implementation details are less relevant, as they study the system in a more abstract (but also more formal) way. Research documentation should also describe the rationale behind design choices and compare the system to other existing solutions.