What about other docs?

Last Update: 12.04.2018. By Jens in Developers Life | Learning | Newsletter

Yesterday’s topic and Alejandro’s reply lead me to another type of documentation. The out-of-code docs. Everything we document about our system which is not in the code or at least close to the code, that can be diagrams, wikis, word docs, whatever.

As he pointed out that code base (code + comments) is not enough for someone new to the project. The new dev needs more info than the code alone can provide.

Yep, that’s true.

Code alone might work if you have enough time to dig through it and the experience and brain capacity to make any sense out of it. But that is inefficient, yet surprisingly happens pretty often.
Not because there was NO out-of-code- docs, no, because of the docs were sparingly AND outdated. What good are abandoned wiki pages were you don’t even know if it’ss till valid and applies to the current state of the system? Or a three years old word doc on a shared drive?

So, can we just stop writing docs?

I don’t think so. Docs are essential. However, it should have a small focus to stay relevant and lower the barrier to update it.

Architectural overview diagrams are a good one as are design decisions, data, and workflows. Along with it what the business actually wanted to have aka what business use cases are we solving. That could be user stories or an old-school requirement doc.

The form is up to you. Just remember to write it for your future self in 6+ month, who has forgotten anything about the system and keep it to the bare minimum, so you actually do update it.