If you’re a software developer, then I’d bet you use some kind of automated testing. And if you don’t, you certainly should. But what about “automated documentation?” Do you know what this means? Are you putting this technique to work for you? Most likely you’re not. And if that’s the case, you’ve come to the right place.
We’ll start out by exploring the role documentation plays in the modern software development world, which has, by and large, embraced agile methodologies. The post will show that yes, documentation is important and valuable even today.
Then we’ll proceed to cover automated documentation. We’ll start by examining the growing trend of using automation to improve the software development process itself, showing how automation has become a must for companies struggling to remain competitive. After that, we’ll define automated documentation and talk about the benefits it provides.
Finally, we’ll get to the tools, where we’ll briefly cover three tools that can help you and your team with your automated documentation strategy, sharing some final tips after that.
Let’s get started.
Software Documentation in a Post-Agile World
Software documentation doesn’t have a good reputation among certain software circles nowadays. There are people who think that worrying about documentation betrays the agile principles somehow. Working software, accompanied by a comprehensive suite of unit tests (they argue) should be all the documentation you need.
That couldn’t be further from the truth.
Yes, the Agile Manifesto’s authors do value working software more than documentation. And they’re right to do so. Documentation would be a complete waste of time if the thing it’s documenting doesn’t work.
But what if you do have working software? In that case, comprehensive, accurate, and up-to-date documentation is one of the key elements that will help you keep it that way.
Automated Documentation: What Does That Mean?
We’ve started this post by covering the need for software documentation, showing how many software teams commonly neglect this area and the benefits they leave on the table by doing so. Now it’s time to take things one step further. Keep reading to learn about the benefits of automation applied to documentation.
Automators Don’t Use Automation as Often as They Should
I like to say that automation is the raison d’?tre of software engineering. And I say that not only because I like to use French expressions in hopes of sounding intelligent, but also because it’s true. I think it’s fair to say that the whole purpose of our field is to employ automation in order to enable businesses and other organizations to solve their problems more efficiently.
So I think it’s ironic, and even a little bit sad, that our field has?until recently?failed to employ automation in order to solve our own problems more efficiently. Sure developers have been automating facets of their jobs since the dawn of software, but only recently have we as a field started to employ automation to its fullest potential. Nowadays automation isn’t only used in isolation, to help individual contributors perform specific and distinct tasks more efficiently. Instead, teams and companies as a whole design and execute comprehensive approaches that make use of automation at all stages in the software development cycle.
In such a scenario, automated documentation is definitely not the one odd out. On the contrary, you might say it’s even kind of obvious.
Defining Automated Documentation
People who don’t really buy into software documentation might have fair reasons not to do so. There are valid criticisms of documentation, and you might have heard some of them:
- Writing documentation is slow, error-prone, and time-consuming.
- It’s hard to prevent documentation from getting outdated.
- Opportunity cost: the time spent creating and maintaining documentation could be better used on other tasks.
The list could go on and on, but you’ve got the picture. Writing and maintaining documentation is a high-cost endeavor. We’d be better off automating one (or most) parts of the process. That would not only cut down costs but also potentially improve the quality of the documentation itself. Finally, lots of additional person-hours would be suddenly available to be better employed elsewhere, on tasks that require human creativity the most. That pretty much sums up what automated documentation is about. So here goes our definition:
Automated documentation is the process of using automation to decrease the amount of human intervention required to create, maintain, and share software documentation, cutting down costs, improving quality and freeing humans from tedious, error-prone work.
3 Tools That Can Help You With Automated Documentation
Now, as promised, it’s time to briefly talk about tools. The tools we’re going to cover in this section are not automated documentation tools, per se. Rather, they are tools that can help you and your team at different stages of your automated documentation strategy. That means they do not compete with one another and are, to some extent, language/platform agnostic.
With that out of the way, let’s get started.
Pandoc
The first tool in our list is Pandoc. Pandoc is a light and versatile tool that can convert to and from a variety of document formats. And how would that help with automated documentation?
Well, with a little bit of creativity, the sky is the limit, really. You could have, for instance, documentation files written in markdown, checked into your source control system, along with your app’s source code. During the build, you could fire up Pandoc, have it convert the markdown files to HTML and upload them to your internal server.
If you have an internal Wiki build with MediaWiki, Pandoc has your back as well, since it can convert to and from the MediaWiki markup.
Visual Studio
It might sound weird to think of Visual Studio as a tool that can help with automated documentation, but it definitely can. For starters, Visual Studio makes it incredibly easy to add documentation to your classes and methods in the form of XML comments. When you build the application, such comments can be exported as an XML file, which can be used as input to generate documentation in a number of different formats.
The professional edition of Visual Studio also offers some features that can help you with documentation. You can add, for instance, a dependency validation diagram. It only allows you to depict the architecture of your app and the dependency between classes, modules and other artifacts. You can also use the diagram to actively validate the dependencies, generating warnings or errors in case the dependency rules are violated.
GhostDoc
Does your team already add XML documentation to all public members of your project? That’s great news, but there’s room to improve. By employing GhostDoc, you’ll be able to automatically generate XML documentation based on the names and definitions of the members. Some of them will still need further customization, but many (or even most) don’t. That’s a good sign, by the way: it means you’re picking good, descriptive names for your classes, methods, and properties.
GhostDoc can do even more than that. It offers spell check for your source code, a visual editor for XML comments, and documentation templates that are StyleCop compliant. Perhaps most important, it can generate and export documentation to a number of formats during your build process.
Automated Documentation is a Must. Start Using It ASAP!
If your automated documentation strategy is nonexistent, then the first step is to get something going, as quickly as possible. If on the other hand, you already have an established approach, you should now be thinking of taking it to new levels.
We hope the tips we shared in this post will help you bootstrap an automated documentation approach at your organization. After you get going, employ the tools we’ve covered here in order to evolve your strategy.
And most importantly, never stop studying. The SubMain blog is a great space to read not only about software documentation but also about coding best practices, C# concepts, and software engineering in general.
Thanks for reading, and until next time!
Learn how GhostDoc can help to simplify your XML Comments, produce and maintain quality help documentation.
