I help clients fix their legacy software for a living, and one of the most common complaints (or regrets) I hear is "If only we had documented this pain-in-the-a*s-service, we wouldn't have had these problems". Despite the best intentions, this is a common misconception and a dangerous generalization that produces more harm than good in the long run.
First of all, not all software documentation is created equal. To subject the project, customer and internal documentation to the same standards and scrutiny would be a massive waste of time and energy because they serve different purposes. The format and contents of a document depend mostly on the intended audience. For example, if you're a developer writing libraries, the developers using your libraries are your audience. Those developers create services and products on top of those libraries, and their customers are their audience. These two types of audiences share a common goal, to get up and running as fast as possible. This is often achieved by creating a system that is intuitive for your audience to use, simple or straightforward to integrate, and documented and configurable in a way that avoids cognitive overload.
Second of all, any form of documentation runs the risk of becoming outdated, especially the internal documentation. Documentation pertaining to onboarding, project setup, library creation, testing, builds and deployment oftentimes comprises various steps that need to be executed in sequence to achieve the same result. Those are ideal candidates for automation. Ideally, you'd have a single command that encapsulates all those steps that were previously documented, and document the invocation example(s) with a short description of what the command does. If a procedure changes in the future, one person can update it, and the rest of the team can continue using with the same effect. For example, I've seen documents outlining the steps necessary to create a Python library instead of using a template, as well as documents describing how to set up your environment to run tests and deploy libraries, tasks easily automated using tox. Not only does automation reduce the amount of documentation you need to write and keep up-to-date, but decreases the surface area of your system, making it easier to use and maintain.
On the other hand, an alternative where nothing is automated and everything is documented is a lose-lose situation, both for business owners and employees. Considering that some, if not most, projects are unique snowflakes, employees can experience micro-frustrations on a daily basis just by using or switching between different projects. Each project can have a slightly different set of steps to achieve the same effect (e.g. run the test suite or deploy), none of which are automated, but some of them are documented. That means they are wasting valuable time on repetitive and monotonous tasks instead of producing something of value to the customers. That's why it's in the business owner's or manager's interest to invest time in automating everything that can be automated, instead of documenting it and hoping for the best.
In summary, documentation and automation have their advantages when applied in the right circumstances. Neither is a silver bullet, so don't treat it as such. The more we automate, the more time we'll have to focus on the things that really matter. As a consequence, the end result will be simpler, easier to user, and require far less documentation.
Top comments (2)
This reminds me of my last project. My current project, on the other hand, has way more automation than documentation, and suffers for it.
I know the feeling :D
That's what I love about the on-boarding process. Each question a teammate poses tells me what's missing and what needs to be documented (or automated). I often encourage them to do the thing they feel is missing. Doesn't matter if they don't cover everything or do something halfway, there's always going to be someone else after them to pick it up and continue the work. Before long, there are no more complaints, most (if not everything) runs smoothly, and everybody's satisfied.