I once worked with a company that hired external technical writers to create content to promote their product. To do my work properly, I needed to understand how the product worked, so I checked out the existing documentation and it was complete chaos.
The documentation was incomplete, workflows were poorly explained, and most of their code snippets didn't work. Suffice to say the documentation was not very helpful.
I had to rely on repeated one-on-one calls with their product team to understand how their product actually worked.
While the conversations were helpful and I was able to eventually do my work, they shouldn’t have been necessary. Documentation should reduce dependency, not create it. I can only imagine how many would-be customers dropped their product out of frustration after trying to follow their documentation.
It was easy to tell that the documentation was not created alongside the product or by technical writers who were carried along in the process.
The Assumptions Behind Most Bad Documentation
In theory, documentation during product development is the standard for most companies. But that isn't always the case in practice, especially at startups, since they tend to prioritize speed over structure.
Most companies operate under the assumption that "documentation can come later."
"The product team will explain it when needed."
"Support can fill the gaps."
"Writers can figure it out after the fact."
"As long as the feature works, the job is done."
They see documentation as slowing down the product/feature shipping. So, they leave the update readme folder in their PR template to remain empty until someone asks somewhere down the line, “Do we have docs for this?”
And then, documentation becomes a cleanup task instead of an integral part of the product.
But documentation rarely works well in hindsight. When documentation is written too late and without the right context or ownership, it may be able to tell users what exists but rarely does it tell them how to use it effectively.
Treating documentation as an afterthought is a significant problem for many products.
The Dangers of Treating Docs as an Afterthought
The first and most obvious downside of treating documentation as an afterthought is that users end up confused and may abandon the product in question.
Beyond that, the following also happens:
- Support teams absorb the load through repeated explanations and tickets.
- Onboarding slows down, especially for self-serve SaaS products.
- Internal teams lose time, relying on meetings instead of shared knowledge.
- Trust erodes, even if the product itself is solid
From a business perspective, documentation is one of the cheapest ways to improve usability and retention. Ignoring it doesn’t save time or money. In fact, it may cost more money in the long run.
When teams prioritize documentation during development rather than after product release, writers can flag unclear flows before they ship.
It also allows the documentation to evolve with the product not behind it and this is especially helpful in the case of products with different versions.
Finally, proper and timely documentation naturally reduces the workload of support and acts as an important part of the product infra.
To Summarize
Product teams must always keep in mind that the product does not end at the UI. It includes onboarding, education, and long-term usability, all of which depend heavily on documentation.
Documentation is part of how users experience a product, even if they never consciously think about it.
When you treat your product documentation seriously, it improves user trust, reduces friction among internal teams and further markets an already solid product.
Basically, everything gets easier with good and timely documentation.
Top comments (0)