I love writing documentation. I know that most others don’t, and completely understand. However, that doesn’t mean you just get to avoid it completely. There are various things about our jobs that are hard, but we still have to do them. Documentation should be no different. I can’t stand it when places have 0 documentation and then tell you to “read the code” to figure it out. Cool, I can totally read code. But your code better be damn good and 100% legible. You better have some consistent docs on your functions. If you don’t, your code probably won’t reliably tell your story.

Now that I work on a company that values documentation, I understand the enormous value that provide. From keeping a journal, to write a spec that will avoid the necessity to explain over and over again the same information to different people. As a developers we tend to look a this tasks as tedious and see no value on them until we face or witness some of its advantages.

Good documentation is nice but there are reasons why it rarely exists. This is not just a matter of laziness.

1. In order to write good documentation, you have to fully understand what you are doing. This is often not the case in software development. More often than not, people don't fully understand the requirements (which is of course also a documentation issue) or they get something working or accepted by copying or pasting code they do not fully understand or by doing some other kind of voodoo. I don't say that this is a good thing in the long run or that it is unavoidable but it often seems to be efficient from a business point of view.
2. Even if you know what you are doing, it is extremely hard to document it in a way that really helps others. Unfortunately, much of the documentation I have read, falls into one of the following categories - and that's surely not because the people who wrote it were stupid:
   • Somebody has put a lot of effort in it, it is nice to read, maybe with many sketches and screenshots, but you don't find what you are actually looking for. You still have to check the source code.
   • Somebody has put even more effort in it and explains everything completely and exactly. It is hard to read and understand, maybe harder than reading the sources. You spend a lot of time on it. Still you are not sure if you got it right and have to double-check it by looking at the source code.
3. And this is maybe the most important point: Software changes over time. It is extremely hard to keep external documents in sync with it.

Again, good documentation is really nice. Unfortunately most of the documentation that exists is not too helpful in practice, even when it has been written by intelligent and competent people. We typically think that we can do it better but it is really hard and might not be worth the effort.

Don't get me wrong, this is not meant to be pessimistic. I am describing the current state of affairs and am sure we can do better in the future. But this will not be easy to achieve and cannot be accomplished with a little bit of motivation. It will probably involve tools that automate part of the process.

Documentation is always a challenge. Not only does a team have to overcome the common aversion to writing it (and I hold my hands up as someone who finds writing docs not as fun as writing code), but there is also the struggle to ensure it stays relevant and up-to-date.

In the same way that data redundancy in a software architecture will constantly cause it's maintainers synchronisation headaches, as will syncing documentation of how code works with the code itself.

I have found that most docs relating to how code works in any sort of detail are doomed to quickly go out of date/sync unless they are inline with the code itself. Even with the best will in the world, people inevitably forget that particular docs exist to be updated.

Even if such docs are available and happen to be up to date, if I'm newly coming in to a project, past experience has taught me not to trust such documwntation too much (for the above reasons), and if you really want to be sure how some business logic actually works, you need to read the code.

So am I saying don't bother? No not at all. But I have found the best approach is to write code to be as self documenting as possible. Good naming and layout of code can help alot here. Where more explicit descriptions are needed code comments can be used.

Well written test suites are also a great way to not only ensure code does the right thing, but to describe what that is.

Where documentation outside of the code can be useful is in describing the high level concepts such as the system design and architecture. These have a fighting chance as they change less often and it tends to be a bigger event when they do. For Http APIs, libs that generate specs for tools like Swagger from the code are also very helpful.

I've worked in places where every problem is met with "we should've documented this better" over and over again. So people document lots of stuff. Problem is it's not challenging the real issues, with the organisation and the code

Imagine you are put on a project already on course and you have 3 days to implement a feature without absolutely no context at all.

I'd quit. Documentation is not the long term solution to this kind of madness.

Another example. Team decided we needed to create lots of documentation for the release process, this is not at all uncommon even when you have CI tools. Documentation is not the solution here, a simple release process is.

I'm not against documentation, but its not the panacea it's often seen as.