Software documentation is a hidden treasure, both when you are first learning to code, when you are an experienced engineer, and everywhere in-between.
I don't know what this existing function does, so I'll make a new function to do this instead! - Someone moments before their undocumented PR is about to be painfully reviewed
Documentation is a not-so-glamorous aspect of programming, but I believe it empowers developers to write better code. In this post, I'll cover why technical documentation can be a superpower, and suggest some easy ways to build good documentation habits.
The history
Technical documentation has existed for a long time. When programs were holes on a punch card, it was an inherent necessity to have some explanation, somewhere, about what the heck that punch card accomplished. As we moved from low-level programming languages (Binary, Machine Code, Assembler) and into high-level languages (C++, Java, Python), that necessity didn't go away. In fact, because there was just so much more code being written, understanding it all required documentation one way or another!
The case for documentation
So how can documentation help you throughout your day to day as a developer? Frequently, documentation separates the good from the great - what use is that amazing project you made if nobody knows how to use it or what it does?
The most immediate value of documentation comes from collaboration. Days, weeks, months or even years after you write code, somebody else will inevitably have to deal with it. Documentation is incredibly helpful for understanding the code that someone else wrote, and done right, saves countless hours of sifting through source code.
Documentation isn't just for other people, though! It also helps the person who wrote the code as well. Have you ever returned to a project a couple months later and failed to understand the code you previously wrote? Often times developers do this and end up writing the same functionality all over again! Documentation helps you save time, because you will understand what your code does at a glance, and you won't have to re-write it a few weeks or months down the line.
Tools of the trade
Nowadays, we are blessed with the internet, and don't have to spend hours sifting through file cabinets to find a technical documentation booklet written a decade ago. Instead, it's all accessible at our fingertips. Here are some great tools for technical documentation hosting today:
1. Sphinx
If you've every worked with Python, you've probably seen this one before, though you may not recognize the name! Sphinx compiles technical documentation straight from source (yes, source code) docstrings. It rounds up all the docstrings found in your source code, and exports it into a convenient HTML format. Although Sphinx is starting to show its age, it is very widely used for building basic documentation websites, and frequently used as the base for bigger and better documentation.
2. MkDocs
Like Sphinx, you've probably seen MkDocs around without knowing it. Made popular by its commitment to using the ever-popular Markdown formatting (just like the Dev.to Community!), MkDocs is widely used for user-facing docs. Think guides, API references, etc.
3. Read the Docs
Read the Docs is quite the tool. In a way, it is an abstraction on top of MkDocs, Sphinx and other generation tools. Its job is to make your docs look good, easy to search, and highly usable.
Tools of the future
The tools mentioned above are all superb, and the market for documentation-related tools is exploding right now. Every company wants to stand out with beautiful user-facing documentation. The downside here is that at the end of the day, someone still needs to write the documentation itself! This will always be a necessity to some degree, but at the end of the day your source code is the ultimate source of truth when it comes to how your project works, and can serve as a strong foundation on top of which documentation can be automated.
I strongly believe that a couple years from now, developers will spend 90% less time writing documentation than they do today. Already, numerous tools exist that can already automate 70-80% of documentation writing processes.
1. Trelent - Docstrings on demand
This one is a VS Code extension that makes documenting your code as easy as Alt+D - literally. All you have to do is click somewhere in the function you want documented, press Alt+D, and the machine learning magic takes it from there. In most cases the documentation it produces is exceptional, but there's certainly room for improvement. It still can't help explain the reasoning behind your most... questionable decisions, and may occasionally get confused if the function name is descriptive of a different task. Nevertheless, Trelent can certainly help explain what your code actually accomplishes, so that the next person to come across it doesn't need to go through quite so much pain.
2. Docstring template generator
This is also a VS Code extension to document your source code quicker than you could otherwise. It doesn't go as far as writing the documentation itself, but it will template out a great starting point for you! If all you need is a quick template to start a docstring, and you don't mind writing the content out, this extension is for you!
Putting it all together
Combining some of the tools mentioned above, both past and present, dramatically improves how developers approach documentation for the better. They make the whole process quicker, more intuitive, and repeatable. Great documentation will make you and your colleagues' lives much easier in the long run - that's why documentation should be known as a developer superpower.
Disclosure: I am a founder at Trelent and thus have a bullish view of the future of documentation tooling and Trelent.
Top comments (0)