ABD – Always Be Documenting

You've written well-thought-out and concise code, so you don't really need to document it right? Wrong. We're all familiar with the experience of reviewing the code comprising a feature, where the nature of its structure, or even its intent, isn't immediately obvious. Worse, we may not know how it integrates with other systems or parts of the solution. By not documenting your code and configuration, and how it integrates with other parts of your solution, you've isolated the group of people familiar with it to a single person, or small team, while introducing the risk that someone may unwittingly impact your solution or services it relies on.

The primary reason that documentation is ignored is because of time, and conflicting priorities. Development doesn't occur in a vacuum, and it's not often that we have the time to stop everything and focus on documentation for our solutions. Apart from designing and development, we also have to consider unit testing, user acceptance criteria and quality assurance, and code reviews (among others).

Documentation is easily pushed to the side for other priorities, and not considered essential. In reality, it can be one of the most important factors for the final, and continued, success of a solution.

Regardless of the task you are automating, it is very likely that you or your team will have to revisit the solution at some point in the future. The purpose of certain blocks of code, exceptions that need to be considered, or even the configuration itself might have faded with time in the minds of the author and those new to the project as a whole may be completely lost. By not documenting your process thoroughly, you incur additional costs in time and effort when revisiting your solution requires additional time to unravel its meaning or purpose. Worse still is the fact that you add additional risk by missing a key component that, while common knowledge during your development phase, has been forgotten.

As developers, when approached with a new system or project, our first inclination is to likely seek out and review the documentation. Next time someone wants to understand your solution, you can simply point them to your documentation. It saves time and effort for you and gives them a helpful reference so that they can self-learn without being dependent on your time and availability.

In addition to this, documentation can make you both a better developer and team member. When working on an automated solution, it can be very easy to get tunnel-vision with a specific configuration or block of code, and how that holistically fits in with the overall structure of the project may be lost. The process of creating documentation during development ensures that you're always keeping the purpose of your project in focus, and it shapes the way that you create the individual components of your solution. There is also an easy reference for yourself, or your colleagues, that can aid in collaboration among team members and increase both the stability and quality of your solution.

Documentation best practices

Now that we understand some of the advantages of documentation, let's take a look at some best practices that will make it more useful to those reading it.

First, understand who the audience is for your documentation. Will it be other developers, or are you providing supplementary documentation for marketing or business teams? Including detailed code blocks and descriptions of their functionality may be critical for developers, but it's sure to drive away non-technical resources on your team. Structure your documentation to match the expectations of its intended audience in order for it to be both readable and effective.

Secondly, create a short, but descriptive, summary of your solution that explains the main purpose and intent of the project as a whole. This will help readers derive the purpose of the solution that you've automated as well as its relevance to their work or other business processes. Also, be sure to provide a description of the main components of your solution, noting any dependencies that may exist within your project. If your solution relies on APIs or third-party libraries, be sure to include their versions inside of your documentation as well.

Be generous with your coding examples when writing documentation for developers. Having a detailed explanation of what a given block is meant to accomplish, and how to both use and test its functionality, can save everyone time and effort when reviewing individual components in your solution. This will also make your code more readable as its intent will be clearly stated, and your solutions will rely less on inline-commenting or naming conventions to express their intent.

In summary, while it can be seen as a distraction or non-critical for a solution, documentation plays a key role in both the development and sustainability of your solution going forward. By empowering yourself and your team with a clear, and detailed, reference, you're incurring future savings of time and effort and ensuring that your solutions are more stable and of higher quality.