Research Spotlight | Documentation is an Act of | Part II
Welcome to part two of this series on the importance of documentation. In the drive to produce new software and to ship as much as possible, the basics of documentation can be overlooked. Documentation provides context and allows someone - be it “future you” or another developer - to get started with enough background information. At Dusk Network we are building the infrastructure for tokenizing securities which we hope will be in use for many decades to come, and as such we are taking good care to document our work so it makes as much sense to a developer in 20 years time as it does to us today.
In a nutshell, the goal of documentation is to communicate just the right amount of information with the right level of detail for a specific target audience. At Dusk, we care about all of the people involved. So, it’s of paramount importance to provide all of them with the information they need.
Documenting is an act of kindness
Documentation benefits everyone. And writing documentation is an act of kindness. When you document your work, you’re taking care of yourself and others preparing for that moment in which something goes wrong and has to be fixed as quickly as possible. It is very common for developers (we are, after all, humans) to forget things. It is not uncommon to have to modify code written ages ago. Will you remember how it works and why? Did you think of alternatives? Did you discard them for some reason? All this information is essential and documentation is there to help fix things easier and faster.
And what if the code was written by someone else? Maybe someone you don’t even know. Can you understand his or her code? Why did they do it this way? Code is always clear to the machine but it might not be straightforward to understand for a human.
Message to developers
Writing code is not much different from writing normal text. You use a language to express concepts. In this case, you use a programming language to tell a computer what to do. The problem is, like with natural languages, different people can express the same thing in different ways. While this is not a problem for the machine, which understands exactly what the code says, it can generate doubts for a human reader: what does this code say? And why? This is where documentation comes in handy: it answers these questions using human language. Of course, human language does not prevent mistakes or doubts, but will likely explain the code in an easier way. And when in doubt, you can always double-check the truth by actually reading the code.
So, if you are a developer, think of documentation as a way to explain to the future you and to anyone reading your code what your code does, how it works, and, ideally, for what purpose. Even when the code is clear, a short summary can save time when someone needs to understand it. The best moment to document a piece of code is when you write it! If you work with GitHub, Issues and Pull Requests can also be a great ally, as they allow keeping track of the rationale and discussion behind changes. Much like history, knowing the past helps us not to make the same mistakes in the future.
The benefit of writing documentation
The very process of writing documentation has another, somewhat surprising, benefit; it actually improves your understanding of the subject. Even when something looks clear in your mind, expressing it verbally can bring up gaps or inconsistencies that need to be clarified. To fill these gaps, you need to expand your knowledge, which in turn improves your understanding, and ultimately allows you to explain better to others. This is something researchers can relate to. Similar to documentation, writing a research paper requires the extra effort of explaining things in a complete and consistent way, which in turn, requires a fuller understanding of the subject. As someone once said (and no, it’s not Einstein): “If you can’t explain it simply you don’t understand it well enough”.
Oftentimes, the solution itself gets improved through this process. If something does not add up in the description, it is possible that something is wrong (or overly complex) in the design. As a result, writing documentation creates a virtuous circle, where each part benefits from the other.
Conclusion
If you’ve reached this point, you should know that the answer to the original question, who needs documentation, is: everyone! Or, at least, everyone dealing with the object of the documentation.
Documentation is an act of kindness. Towards yourself, others, and the product itself. When you have to fix a bug in that code written ages ago, you’ll be grateful for that short explanation you wrote above it. When you have to understand that convoluted piece of code written by someone you don’t even know, you’ll thank them for that clear description they left there. But most of all, when you’re not working on that software anymore, and somebody else is able to carry on your hard work and build something on top of it, your own product will live on.
Future
In the following months, I'll be studying and documenting all of the main Dusk Network components and protocols, sharing my newly-acquired knowledge in dedicated posts. I will explain Dusk nodes and their interaction within the network, the Dusk blockchain with its transactions and smart contracts, and the consensus protocol that allows Dusk to have a distributed, fast, and secure ledger. I will try to explain everything in simple words so that both experts and beginners will be able to understand. And if I fail… you can always read the code ;-)
