I am always posting provoking post on my Linkedin, and I have decided to replicate those here. Let’s socialize!

Why do people mistakenly think that documentation is a critical success factor in software development?

Documentation should be concise: overviews/roadmaps/high-level diagram/guidelines are generally preferred over detailed documentation.

Never forget that developers rarely trust documentation, particularly detailed documentation because it’s usually out of sync with the code.

You should understand the total cost of ownership for a document, and someone must explicitly choose to make that investment.

Ask whether you NEED the documentation, not whether you want it there as a security blanket

We certainly don’t need “just in case” documentation. We need just enough documentation to make sure the team is successful.

Your team’s primary goal is to develop software; its secondary goal is to enable your next effort.

Documentation is a necessary evil; the project cannot survive without it. For this reason, we need to find ways to do just enough documentation — no more, no less.

Your team should classify the code as a major, if not the primary documentation of the software.

The rationale for the code being the primary source of documentation is that it is the only one that is sufficiently detailed and precise to act in that role.

Free Advanced Java Course

I am the author of the Advanced Java for adults course. This course contains advanced and not conventional lessons. In this course, you will learn to think differently from those who have a limited view of software development. I will provoke you to reflect on decisions that you take in your day to day job, which might not be the best ones. This course is for middle to senior developers and we will not teach Java language features but how to lead complex Java projects.

This course’s lectures are based on a Trading system, an opensource project hosted on my Github.