DEV Community

Cover image for How to avoid comprehensive documentation/ over-documentation?
Aga Zaboklicka
Aga Zaboklicka

Posted on

2

How to avoid comprehensive documentation/ over-documentation?

Hi!
I think one of the teams I work in is overdocumenting things. It's we do waterfall-like iterations (I work on legacy systems and we do both change requests and production support), and there is some kind of document written at every stage of the project:
1) collecting requirements - the first document
2) after the project was accepted - another document with the same requirements but with more details
3) than high lever design for the system - general architecture overview
4) than more detailed system design up to the point of describing code
It's pretty exhausting and I was wondering how to do it in a smarter way.
What are in your opinion best ways to do project documentation?
Or how to talk the team into more collaborative documentation? I'm not sure how to start the stone soup here...

Any automation tips/ideas?
For example, for the requirements, I'd like to create one document and extend it over time instead of writing the documentation from the scratch every time and duplicate the information...

Sentry image

See why 4M developers consider Sentry, “not bad.”

Fixing code doesn’t have to be the worst part of your day. Learn how Sentry can help.

Learn more

Top comments (2)

Collapse
 
nektro profile image
Meghan (she/her)

Documentation is definitely great in volume but keeping the quality is also if not more important. So I have two questions, are all four of these separate documents, and separate from the code?

2 and 3 seem like they could be combined, and the detail at which 4 goes into seems like it would be more useful as comments in the /** */ fashion.

Collapse
 
agazaboklicka profile image
Aga Zaboklicka

Yes, everything is separate. Some projects require even more documents. I understand the value of good documentation, but it's more about the process here. I remember writing high-level design, software system design and then describing the actual changes.

It'll be hard without a design - the think before implementation is important, but if the design has to be rewritten every time we miss the point...?

I believe that we can write 2 and then extend it to the new document by adding extra changes eventually. (You know, deliver 2 and 2-based 3 or 3 and 3-based 4) I never read any documentation, but the code isn't self-documenting itself either. It'll require the contribution of every developer.
The documentation is always written quite early and then we need to rewrite it.

Billboard image

The Next Generation Developer Platform

Coherence is the first Platform-as-a-Service you can control. Unlike "black-box" platforms that are opinionated about the infra you can deploy, Coherence is powered by CNC, the open-source IaC framework, which offers limitless customization.

Learn more

👋 Kindness is contagious

Please leave a ❤️ or a friendly comment on this post if you found it helpful!

Okay