When you work on a software project, someone will eventually ask a variation of this dreaded question - "Do you know where I can find documentation for this feature?" or "Do you know why we implemented pattern x over pattern y?" or my personal favourite "What the heck does this piece of code even do?". Unless you are blessed with a photographic memory, you would typically respond with a "I don't know" or "No idea". This is followed by an embarrassed look, a shoulder shrug and an awkward joke about how devs HATE documentation.


If there is one crime that the Agile manifesto has committed it must be the act of declaring documentation an inferior activity in the software development process.  "Working software over comprehensive documentation" - the manifesto unceremoniously proclaims. This proclamation gave the busy and sometimes lazy developer an excuse to renounce documentation in all shape and form without remorse. You are disinclined to dispute this statement in the manifesto because it would mean you are arguing against agility.  My opinion, based on 15 years of experience, is that this statement (taken literally) has caused more long-term harm than good. Some devs claim that their code is "self documenting" and enthusiastically eschew comments in their code, and squander the perfect opportunity to document and capture context for others and their future self.  Documentation is so much more than just "comments in code", it's a tool to improve the quality of the software you are building.

If there is one crime that the Agile manifesto has committed it must be the act of declaring documentation an inferior activity in the software development process.


Clear and up-to-date documentation - like meaningful code comments, high-level technical design spec (that tracks evolving design decisions), data dictionary, entity relationship diagrams - is the secret sauce to make your design and codebase maintainable. It will drastically reduce on-boarding time for new team members (junior or otherwise). You will spend less time trying to comprehend your code and design (or explaining it to others), or second-guessing the whys and hows of the implementation which could sometimes lead to incorrect conclusions because you lack (or have forgotten) the original context. Another surprising benefit of a well documented project is that the lead time to reduce technical debt will be shorter. It will help retain the team's institutional knowledge (accumulated over the years) which in turn will improve the team's bus-factor : when that "rockstar" developer or architect leaves the company, the project won't all suddenly fall apart.


Just like flossing, developers know that documentation is good for them but they still don't do it as often as they should. Creating the habit and discipline to document (at a minimum) your code, data model and design decisions in a structured manner will pay off 10 times over in the long run. Spending time documenting during design & build will affect your "agility" by a small margin but the benefits far outweigh this minor cost. Your current and future team members will thank you for it.