DEV Community

Wade Zimmerman
Wade Zimmerman

Posted on

Documentation Frameworks

Legacy code bases are full of knowledge gaps, and there is no good way to learn effectively.

The problem starts with senior devs or the people before you. Everyone thinks their code is perfect, so they never stop to document anything. Overtime the lack of documentation compounds and becomes an unmaintainable mess.

Yes, a good developer can read the code and use a debugger to figure out what a piece of code does, but they are missing the bigger picture. Sometimes, a piece of bad code exists because it solves a very specific problem. Usually this can be solved by writing a comment in the code.

Where things become a problem, is when a developer makes years of assumptions and/or works in isolation. The programmer will have a perfect understanding of the code, but nobody else will. The code is almost a mirror image of the devs thought processes, and since everyone thinks differently, it is extremely difficult to decipher years-worth of code.

With documentation, programmers can provide an overview of what the software does. They can talk about the flow of the application or the problems that are solved. Any documentation that shines a light on why certain code exists can greatly improve the team's understanding of the code.

What is weird to me, is many open source projects have ideal documentation, and they aren't even getting paid. Yet people who program for a living, never document anything.

Some developers will blame this on management. I agree that management needs to allocate more time to documentation, however, if developers ignore the importance of educating the team, then there will never be enough time.

There needs to be more frameworks for spinning up documentation. Many existing solutions exist for API-level documentation, but many teams need something generic. A framework which easily allows searching, navigation, and breaking down pages into sections.

Every time I made a push for more documentation, I would get responses like "Documentation is just a snapshot", "It's easier to read the code", or "Read this 200 page paper".

What does it take to convince the team that documentation is worth the effort? If documentation was easier to produce, would teams use it?


Personally, I think there should be an elegant framework for producing docs. Something that makes writing docs as easy as publishing to dev.to. Something that can be wrapped up in a python package or npm package.

Discussion (0)