The Automated Documentation Creation Tool for Developers
As a developer, I spend a great deal of time writing the code that drives our software so that it works exactly how I want it to. The beauty is in the details, and that’s definitely true when making hundreds and thousands of small changes within the code, all of which can be vitally important.
To help me remember why I made those changes, I create documentation that is embedded within the code. Since, many of the projects that I work on are often shared or reused by other developers, it’s essential for the code library authors to provide this detailed documentation for “client developers”. In fact, a library is only good as its technical documentation, because even the most useful, well-written libraries can’t be easily understood without technical documentation.
Since there is no set strategy or style for documentation, it typically falls on the shoulders of the developer to provide what they believe is necessary. This documentation can range from very a high-level description to a detailed breakdown of every element within a library. It really comes down to the authors of a library and what they feel will be sufficient for other developers to understand the code.
When a library is being built and used internally, the documentation needs to be more detailed and insightful since it will also be used to describe the design strategy so the library code can be maintained. In addition, a high-level technical overview is required to help communicate how to use it as a black box.
Numerous tools have been built to author, maintain and publish different levels of documentation. Each tool typically supports select technologies and is for different audiences.
At Azavar Technologies, we build web and mobile apps using Microsoft technologies, mainly ASP .NET MVC, C# and Xamarin, in addition to Sitefinity CMS. We also use GitHub as our primary source control tool to host our code and technical documentation formatted as markdown.
We use Microsoft Visual Studio as the main code authoring tool, and the native XML Documentation integration based on comments embedded in C# code. This tool does a good job of helping us add technical documentation to code, but it still requires developers writing client code to continuously review the library code when needed. This was ultimately an inconvenient solution as developers are naturally drawn to read code rather than comments when both are available in the same document.
To address this inconvenience, we recently built a simple tool that uses the already-provided XML documentation feature in Visual Studio to automatically generate GitHub-flavored markdown files containing the documentation. It’s a fast and easy solution that creates files that can be added to the repositories and viewed in a web browser. And best of all, we are making this tool open source for everyone to use and extend with your contributions and feedback.
This tool provides the opportunity to automatically embed technical documentation in code. It also creates a nicely formatted markdown version containing only documentation so developers can concentrate on using libraries rather than wasting time reading through the code.
Let us know what you think!