Documentation - When and Why You Need It

Documentation is often a dreaded topic (and task). Yet, we continue to advise taking the time to do it. And if you're on the other side of the fence, your team is grateful when they have good documentation to work from.

Is it worth the time to write it?

Perhaps more than any other aspect of a project, the amount of time simply understanding it can be one of the biggest hangups. That's why any project manager worth their salt will explain to you that merely adding more team members to make a tight deadline doesn't actually speed up a project: those new team members don't have the domain knowledge, they may need to spend weeks getting it, and they may even slow your already productive team who then feel the need to facilitate on-boarding people.

This is where documentation can fill a gap. High-quality documentation profoundly improves the spin up time of a developer. On the other hand, that means your paying someone, maybe a multiple people, to write about the code and the project, and to update it. No small feat, especially if you have an expansive project! In the moment, it may seem like an easy corner to cut.



It will always help you. But that doesn't mean it has to be a huge sacrifice of your team's time.

Accessible, Efficient, Readable

So let's talk about some grate tools called "Documentation Generators". There are several tools on the market, like Slate and SwaggerDocs, which collate specially formatted comments that developers can write straight into the code. While it takes a few moments more from your programmers to enter these comments, its a fraction of the time otherwise required by a separate, full team to write from scratch. On top of that documentation generators often create beautifully formatted, interactive, docs, and they usually put them all in one place that is accessible, like a web page. Perhaps the greatest time saver of all is that it keeps everything updated: as new code with comments is added or deprecated, the documentation will reflect that.


When was a time that good documentation helped your project succeed?