[hw]

What many dont realize is that documentation is tech debt. You can spend a lot of time and write a lot of documentation and have to also spend time updating it.

I have worked with teams that focus so much time on design docs and insist that everything has to be documented. Pace of work is slow. Documentation and designs became obsolete due to shutting down of services, change in architecture, refactors.

The best form of documentation is code.

[tshaddox]

I think it’s a bit odd to call it tech debt. I’d say something more like “documentation is part of your tech, and needs to be maintained like the rest of your tech.” It’s only tech debt if you decide to not maintain it.

[beckingz]

Agreed. Documentation has upkeep costs as the software and environment change.

[dnsmichi]

> The best form of documentation is code.

Documentation as code might be a good alternative path, using the same tools and processes as software development and embed documentation tasks into engineering workflows. More insights in https://about.gitlab.com/blog/2022/10/12/five-fast-facts-abo... how the GitLab technical writing team collaborates.

Note: GitLab team member here.