The importance of good Documentation

We all know documentation is an important part of any software. Whether that is through self-documenting code or hosted documentation on dedicated websites. In the end, all that matters is the quality of the documentation.

I've been in software development for most of my life, and so consuming documentation, tutorials, guides or otherwise, has been part of most of my life because of that.

Over the years I've dealt with everything from completely missing documentation to the most complete and comprehensive documentation imaginable. And of course everything in-between.

The most common form of documentation, however, is within the files I'm dealing with. In the end, as a software developer, most software I'm dealing with has been written by the team I'm involved in, and usually no disconnected documentation is written. In the end, this typically means two things. Software without comments, or software with comments.

In the past, I've written about self-documenting code and its importance. And I still stand by this fact. When dealing with software development teams, there's no way there's time for maintaining proper documentation. Practicing the routine of having well-named functions, variables, and filenames is easier than having to explain in your code what everything does.

And this brings me to the opinion that documentation has to be either good or non-existent. If you have a different view on this, I'd love to discuss this with you. It's always interesting to hear different approaches, and I'd love to be proven wrong!

Whenever you, or anyone in your team, decides to write external documentation, you (or your team) will have to continuously put in the effort to maintain this documentation. Make it part of the routine to update whenever relevant products or tools get updated, and whenever you estimate anything related to these tools, also estimate the time it takes to update the documentation accordingly.

And here's why; As soon as the documentation is slightly outdated or incomplete, those reading the documentation can assume two things. Either the documentation is outdated and they'll have to figure things out for themselves, or they've discovered a feature that might, or might not, be not intended to be used.

When you encounter undocumented features, you'll need to ask yourself if you want to use this feature. There can be consequences of using them, and I think most people in software development have had to deal with this. Often undocumented features can be broken in future versions. Either intentional or unintentional. There's a big chance they're undocumented for a reason. They might be pending deletion once the final piece of software using it is rewritten, or they might not be feature complete yet and have breaking changes in the near future.

In any case, once you find undocumented features you need to do your own research. When it's software written by the same team, you can simply ask the person who wrote it (Thanks git blame!) and get your answers. But if the software is from a 3rd-party, you can either never know the answer, or you'll have to raise a ticket and hope for a proper, and timely, response.

And this is exactly why documentation needs to be up-to-date, or non-existent in the first place. If there was no documentation at all, and the software was simply self-documenting, you wouldn't have to worry about any of this. But if any documentation contradicts the actual software, you can get down to endlessly researching what part is the supposed truth. Is it a bug? Is it an undocumented feature? Is it an accidental commit that slipped through code review? Or is it simply a forgotten piece of software that should've been documented in the first place, but there was no attention given to it.

All I'm trying to say, is to make sure you consider what you document and schedule time for maintenance every time the software is changed!

And this doesn't just apply to your (or your team's) codebase, but also to SaaS and other software where the user doesn't touch any code at all. If you document something, document it well, or omit it completely. Humans are remarkably capable of figuring out things for themselves, but if they're told to do things according to specification and it doesn't work as expected, you raise questions.

In the past 4 years I've worked as a Developer Advocate for several companies, and if there's one thing I've learned over the years, is that most questions come from incomplete or outdated documentation.

The number of questions I've had cross my desk about documentation that was forgotten about and completely outdated/non-functional by the time the user in question started using it, is insane. But whenever software was released undocumented the questions were mostly due to bugs in the software, not because of the lack of documentation, and those questions will be there regardless of documentation or not. And trust me, this was not due to lack of adoption.

Conclusion

So in conclusion? Well, I've already said this a few times, but it can't be repeated often enough. There are, in my opinion, only two routes you can take.

1. Omit documentation

Omit documentation en and make everything either self-documented (in case of SDK's/code files) or intuitive (in case of SaaS). In both situations here developer/user experience should be on top of your mind

2. Always update documentation accordingly

Write proper documentation, and always keep it up-to-date. Schedule time every time the SDK/product gets changed to make sure the documentation is up-to-date, and simply never let this slide. As soon as you forget to update your documentation once, it's easy to do it more frequently, and before you know it, your documentation is a dinosaur and doesn't help your users at all. It hurts adoption, productivity and maybe even your company.