“Everything automatable will eventually be automated.” Have you heard that saying? I’d prefer to tweak it a little bit and say that everything automatable should be automated. If you’re a regular reader of the SubMain blog, you’ll know that we enthusiastically advocate for automation. In today’s post, we continue that trend, focusing on documentation generation. More specifically, we’ll walk you through some essential features you should consider when trying to pick a C# documentation generator.
The Case for a C# Documentation Generator
We’re about to dive into the essential C# documentation generator features we’ve just promised you. But before we get to that, we first need to convince you that a documentation generator is something worth your time and attention. If you already agree with that, feel free to skip this section. Otherwise, keep reading.
First of all, we need to address the issue of the importance of documentation itself. Nowadays, it’s not rare to find developers that dismiss software documentation?automatic generated or not?as nothing more than a relic of the past, a time capsule from the ancient times when we were all using waterfall, and that somehow managed to survive to our era.
That couldn’t be farther from the truth.
Software Documentation Isn’t Just One Thing
First, understand that software documentation comes in all shapes and sizes. Some may believe that documentation is nothing more than source code comments, but it goes way beyond that. If your application exposes a public API that other developers can talk to, you should document said API.
Yes, you can and should document the code itself. Maintenance programmers?or maybe your future self?will thank you for that.
Software Documentation Remains Crucial
Once you know the different types of software documentation, it becomes easier to see why it’s still important. You have to document your source code to make the lives of its future readers easier. Sure, writing clean, concise, self-documenting code is a recommended practice, and you should aspire to do so. But self-documenting code alone often isn’t enough to supply all the information needed by the reader. And even if it’s enough, sometimes you don’t have the time to sit through thousands of lines of code.
You must document your APIs. If you don’t, you risk alienating your userbase, which will then flock to your competitor who has a better-documented solution.
Software documentation is not a relic of the past. It’s a modern business need. If you don’t document your software, you lose money, plain and simple.
The Many Pains of Manual Documentation
Now you’re hopefully convinced that software documentation is worth it. The next question then becomes “Why automate software documentation?”
The answer is “For the same reason you automate anything else.” That is, to solve the many problems that arise from performing the task manually.
First of all, a 100% manual approach to documentation would be too slow. Not to mention tedious and error-prone, but that should probably go without mention. But the biggest issue here is the risk of the documentation getting out of sync with the software. Lying documentation is worse than no documentation at all. The potential for catastrophe is just too high. You’d be better off having no documentation than having outdated documentation that can lead developers to make decisions based on obsolete information.
C# Documentation Generator: 5 Features You Should Look for
Up until now, we’ve covered:
- why software documentation is still essential; and
- why you need to automate most of it
Now it’s time to finally dive into the list of features you should look for in a C# documentation generator. We’ll be covering five important characteristics you should be aware of when trying to pick a C# code generator.
Source Code Spell Checker
It might seem weird that of all possible features, we’d start the list with “source code spell checker.” Many of you might not even know that’s a thing, but it is. And more than just “a thing,” a code spell checker is one of the features you definitely should look for in a C# documentation generator. Bear with me.
How could you benefit from something so seemingly inconsequential as a code spell checker?? We have a whole post dedicated to answering just that question, but we’ll offer a brief answer here as well.
For starters, globalization is a thing. We live in a world where you could have teams comprised of people from virtually all countries in the world. For the vast majority of them, English isn’t their first language. So, spell checkers can come in handy here.
A source code spell checker also discourages some not-so-great naming practices, such as the abuse of acronyms and non-pronounceable names. And as a bonus, this will also make it way easier to search through the codebase in the future.
Bootstrap Your Documentation
The hardest step in a journey is often the first one. So a good documentation generator must give you a headstart, by providing you with a documentation scaffold that you can then tweak and edit until it fits your needs.
Generate Help Documentation From Build
Continuous integration is, fortunately, a standard practice for many software teams nowadays. Long gone are the days when teams?or even whole departments?worked in complete isolation from one another for many weeks or even months and then suffered through the seemingly unavoidable chaos that ensued when trying to integrate all of their work.
So, it goes without saying that a good documentation generator, for C# or another language, should integrate as seamlessly as possible with your existing CI pipeline. That’s why being able to generate documentation during your build is one of the essential capacities you must keep an eye out for.
Documentation Batch Actions
Here’s a feature that, while not as crucial as the previous ones, will save you tons of time. When searching for a documentation generator, make sure that it can generate documentation for many artifacts at once. For instance, assume you’re able to generate XML documentation comments for the members of a class. That’s great, but being able to generate the documentation for the whole class would save you a lot of time. But why stop at the class level? Why not generate the documentation for an entire project?
Being able to perform those documentation generation tasks in a batch will save you hours of dreadful work, time that can and should be put to more valuable use.
Visual Editor for XML Comments
Editing XML documentation by directly changing the code isn’t always a great experience. You’d often need to look up the correct syntax of the XML comment tags, what is the correct format to use, and so on. What if your XML comments start to get more advanced, with the addition of code samples and HTML? Then it gets even harder to make sure they’re all valid compliant XML.
That’s when a visual editor might really come in handy. With a good WYSIWYG style visual editor, adding and editing XML documentation tags become quick and painless.
The Takeaway
Even though many developers seem to be under the impression that software documentation is a thing of the past, it’s still as crucial as ever. Excellent documentation is a tool to ensure your software organization remains competitive.
And to have excellent documentation, automation is crucial. Today’s post focused on a specific aspect of automated documentation, telling you about some properties of a great C# documentation generator. Based on the list of features you’ve just read, you should now be equipped to make the best decision for your team or company.
Learn how GhostDoc can help to simplify your XML Comments, produce and maintain quality help documentation.
