Devs and docs

by Alex Ionica

cover-image

Whenever we create/setup/configure/design something new, we should document it. It sounds like a chore and nobody wants to do it, but we need it.

I would clasify it as a matter of discipline, just like commit messages or naming conventions.

All the projects I’ve worked were lacking documentation and this causes multiple problems. From disruptions, people being asked questions several times to poor understanding of how things work or should work, which leads to inconsistent code bases and then http://www.darkcoding.net/software/facebooks-code-quality-problem/

Documenting something also consolidates your own understanding.

How to write documentation is another question and I think it’s something that needs to be presented to the team as samples.

Same thing also goes for creating specs. Here is an interesting article about specs. http://www.yegor256.com/2015/11/10/ten-mistakes-in-specs.html

Why is documentation ignored? The main reason I hear is time. Things need to get done and there’s no time for docs. And unless it comes from up stairs it will probably stay this way.

Comments