02.07 Document configuration steps to be automated

People sometimes ask, for whom are we writing documentation? My answer is a robot. You write code for other people; you write documentation for machines. This is because documentation often serves as a checklist for “stuff that we will automate later” (whether – at the time – we think it can be or not). Robots don’t like assumptions.

So that users/readers aren’t riddled with step after step in your instructions, you might link to common pages that we’ve written – such as an “AWS development environment” readme/page that describes that process. In one README I was going through, the particular instructions referred to an /opt/aws directory. A robot wouldn’t know what to do with this information unless it you told it to create the directory or to use an AMI that already had this directory – and so forth. To successfully get through this README, I also happened to know I needed a git client installed, but the documentation didn’t state this. I can’t rely on a robot to just “know that implicitly”. These assumptions have people rely on some level of tribal knowledge and while that might be okay for a small team, it’s definitely not okay once you have multiple teams in a larger organization. Some follow the contemptuous “you must not be a real developer” argument when it comes to writing documentation. To me, clear READMEs/Doco are a crucial part of the overall user experience – even if you’re assuming your user is actually a robot.

Rather than focusing on the repetitive nature of this type of documentation, a better question might be why not have a standard/referenced CloudFormation template that configures an “AWS development environment”? By writing a bunch of “unnecessary instructions”, you might figure out that it’s something that can be automated or we can just refer to the “standard development environment” instructions so that the reader doesn’t get “overwhelmed” with the instructions. It’s not about whether someone does or doesn’t have git installed (or how this might even affect their “tech cred”), it’s about what is being assumed and what can be automated.

I can’t expect that a robot to know to look for the Physical ID for the JenkinsSdbDomain Logical ID in CloudFormation unless we tell it how.

Earlier in my career, I had someone who said something to the effect of “if there are errors in the software we write, we’ll get paid to fix them”. There are people in our industry who believe that if they make it a little difficult for the customer, then they can lock those customers in forever – as they’re dependent on them. We are not those people.

For more information on this, see Readme-driven development and Documentation is for Robots.

Leave a Reply