DEV Community

Cover image for Fixing your Documentation Problem

Fixing your Documentation Problem

Nick Cinger on October 27, 2018

You might feel like you don't really have a problem, but statistically speaking, you probably do. And even if you do have documentation, there are ...
Collapse
 
mortoray profile image
edA‑qa mort‑ora‑y

Documentation has this nasty problem of becoming outdated. It can be infuriating to have stale documentation. It's often worse than having no separate documentation at all.

Docs should be left for high level things that don't change often, like the overall architecture, or module descriptions. I disagree with documenting individual files or classes. If you do, then it must be directly beside the code it's documenting (in the source code) to at least have a chance of being up-to-date.

If you're using docs as a design tool, then fine, but throw them away after it's been implemented.

Collapse
 
nebojsac profile image
Nick Cinger

Documentation has this nasty problem of becoming outdated. It can be infuriating to have stale documentation. It's often worse than having no separate documentation at all.

Agreed 100%. That's why I propose documentation be updated before you write that new feature or update. More often then not, developers forget to update the documentation after the update's been pushed.

Docs should be left for high level things that don't change often, like the overall architecture, or module descriptions.

Also agreed! I guess it wasn't clear in the post but I didn't say you have to document every nook and cranny in the code. What I was saying, in the excuse section, was that documenting within the code is not a valid excuse to not have proper standalone documentation. In an ideal world you would have both good high-level documentation and accurate docblocks.

Collapse
 
johnmccuk profile image
John McCracken

Couldn't agree more, the risk of refactored code linked to legacy comments is too high.

Always believed a summary doc block along with well named variables/method names should provide enough guidance for very little additional effort.

Although coming up with well named variables is another challenge in itself.

Collapse
 
nebojsac profile image
Nick Cinger • Edited

Doc blocks are mandatory, imho, but also a separate topic. The problem is that a lot of developers use the existence of docblocks and code comments as an excuse to not have to do non-code documentation.

I argue, in the post, that non-code documentation is also important, because it fills a different role than in-code documentation. Ideally you would have both!

Thread Thread
 
mortoray profile image
edA‑qa mort‑ora‑y

I'm quite undecided. On most projects that had architecture docs, I was the person to write them. I never referred to them again, nor did anybody else.

I can see them being helpful should I disappear from a project, but I'm not convinced they are essential. They also take time, which is time not spent doing something else.

Thread Thread
 
nebojsac profile image
Nick Cinger

That's fair, I'd say it depends somewhat on the project. But also, fixing the knowledge silo is, long term, a thing worth doing for the project. That's an extra point I could add to the subject, thanks for that :)

Thread Thread
 
nestedsoftware profile image
Nested Software

I was the person to write them

Found the problem! Hehe ;)

Collapse
 
docsbydesign profile image
Bob Watson

How likely the docs are to be out of date or inaccurate is inversely proportional to how highly they are prioritized by the people who are changing things to be documented.

But, one size does not fit all.

The important takeaway from Nick's article is to make documentation a conscious design decision instead of a default (or ignored) one. Understand and decide for what you will need documentation and why, and then act on those decisions. Know to whom you need to communicate, what they need to know and why, and the best way to communicate that to them.

Collapse
 
kosm profile image
Kos-M

I've been in a project , and after finished , had to make all docs from beginning..
It was pain..

I think documentations should evolve as project is growing.. i mean for example
Documentation should be part of adding/modifying a feature and if a dev mark a feature as completed without documented that along the code implements that , should never accepted.

P.S if anyone has to suggest quick tools for small documentations , please share :)

Collapse
 
erickmendonca profile image
Erick Mendonça

I typically meet with my team to plan our solutions and then we take notes of some.l decisions like interfaces, patterns, data structures and such. I'll try to write it down in a cohesive way next time and push as documentation. Sounds good.

Collapse
 
nebojsac profile image
Nick Cinger

That's already better than what most do, so you have a head start! There's always more you could be doing of course, it's just that making it a required step in the process will keep you more consistent at it. Thanks for sharing your experience!

Collapse
 
webdva profile image
webdva • Edited

You made a well presented case for making the effort to write documentation. You even compelled me to add more documentation writing into my process.

Collapse
 
nebojsac profile image
Nick Cinger

Thank you for the feedback!

Collapse
 
capu profile image
HD

Hello, thank you for the post, could you please share what tools you recommend for documenting?
do you use chart? could you share an example?😄

Collapse
 
nebojsac profile image
Nick Cinger

Hey, glad it could be useful!
We use Markdown for writing documentation. Recently started moving to Confluence, but there are good free tools out there as well. For charts, I use draw.io and export to PNG.