This post is not about RTFM^[1]. It is also not about commenting every public and private function in your code, just to increase the amount of comments. Since I read Clean Code by Robert C. Martin I try to write as few comments a possible and dispize those useless and auto generated ones, which repeat what ever the method signature already tells you. Instead, this post is about writing useful and actionable documentation for you and your fellow colleagues. Yes, also for yourself, so that you don't have to remember everything at all times.

Useful & Actionable

What do I mean with useful and actionable in regards to documentation? From my perspective, in order for documentation to be useful, it should be up to date. Outdated and wrong documentation is often times worse than none at all. In order for it to be actionable, the documentation should be composed of simple if-this-then-that instructions or short tutorials with copy-paste code and command samples.

README.md, Wiki, (Word) Documents

These two goals, keeping it short and allowing for easy updates, make a simple README file the perfect place to store your documentation. The developer can modify it right from their IDE. There's no barrier which inclines one to postpone and eventually forget about those updates. Sure, many hosting services for version control, such as GitHub or Bitbucket, but also some self hosted alternatives, offer wikis or similar tools for keeping documentation. These tools might be great to keep track for high level concepts and document what your team agreed upon, in order not to repeat the same discussions over and over again, however, that's not the type of documentation I mean in this post. Oftentimes, in former companies I've seen that documentation was stored in word documents. I believe, you all have experience with at least one word document like that. Of course, when it's used to communicate with the client, it's probably the best from many bad options, but as I already mentioned, that's not the type of documents I'm interested in, in this blog post. In some cases however, I've been handed word documents on my first day at work. They described, how to set up my development machine, and how to get a local version of the system up and running. Needless to say, because it was so inconvenient to update them, these documents were oftentimes ...

• ... incomplete.
• ... outdated.
• ... needlessly way too detailed and cluttered with information not relevant for me at that time.

Why should it be easy to edit documentation?

This sounds obvious, who would want anything to be complicated. However, making it easy has more implications than you might think at first. It's quite unlikely, that the first iteration of a feature will be complete and correct, so why should it be any different with documentation? I checked the README files of our 3 most commonly used repositories and basically every second - every third developer in the company contributed to each of the files. In open source repositories we expect a good README, otherwise we'd be lost. So why not maintaining the same level of quality in private repositories?

Call to Action

If your repository doesn't have a README yet, create a new one. Maybe you can populate it with some essential parts from existing wiki page or documents. From now on, every time you notice an error in the README file, just update it. If someone asks you to clarify parts of it, do it and ask them to update it. You'll have useful and actionable documentation in no time, which will make your life easier.