Striking the right balance

While considering documentation automation, or documentation operations (DocOps) as some call it, it’s too easy to take things too far. You can automate and test so many aspects that the documentation becomes almost as complex as a code base. Documentation is often the first point of call for people who want to contribute to open source projects or a place for less technical team members to contribute things that those with a more technical mindset might have missed. The key to implementing a good balance for automation and testing is to add tooling that helps enhance someone’s contributions without blocking them with unnecessary complexity. If someone wants to update a spelling error in a document, should they be required to jump through multiple hoops to do so?

Many of the same code automation and testing rules also apply to DocOps. If tests are unreliable, “flakey,” or frequently fail for unknown reasons, are they useful...