Bamboo Blog

I wrote previously that we always keep the documentation at a minimum. How can we then avoid documenting things like build procedures or deployment procedures?

5. Don't document it, automate it!

If we find ourselves in the situation where every team member needs to know any non trivial process, which is often repeated, we try to automate it. Ruby offers great tools to do it, like Rake, Thor or Capistrano. Usually you just need to know how to execute the command. If you need to know the details, you can always look inside the script's implementation. This saves a lot of your own time as well as time spent on educating others.

6. Documentation as a last resort

Sometimes you may find yourself in a situation, where certain processes can't be automated. For example a customer's production server has some extra security restrictions and the only way to deploy your application is to login to the server and follow the manual steps. Since this information may not be used frequently, it can be difficult to keep it in your head (and why should you bother keeping it there?) For this kind of information we use wiki pages. There are lot of wiki frameworks available. Sometimes we don't need the whole wiki engine with all it's features but just a Dropbox with markdown files or a structure of folders and files in a Git repository. We always try to be pragmatic and use simple solutions, best for specific projects. Documentation is evil though, it often gets out of date, so if we have to use it, we try to reduce the amount of it as much as possible.

In the next article I will write more on our knowledge sharing techniques.