Lately I have been involved with open source projects that struggle with their documentation. It's easy to identify bad documentation out in the wild - many of us have an intuitive sense when a project's docs are hard to understand.
#documentation #opensource #writing #techdocs
/1
It is not surprising that most of the "bad docs" are maintained by software engineers, and unfortunately we do not apply the same rigor to our documentation as we do to our code.
#documentation #opensource #techdocs
/2
To get our docs quality to match our code quality, we need to treat our documentation as a software design problem. Just like our code, we need to write documentation with clear goals of what problems we are trying to solve (and for whom!), a vision for our ideal end state, an understanding of the tools at our disposal, and a plan to organize our ideas.
#documentation #opensource #techdocs
/3
The good news - software engineers know how to do these things, or can find help along the way!
My thoughts in detail here: https://adambkaplan.com/post/2025-03-15-docs-software-problem/
#documentation #opensource #writing #blog #techdocs
/end
Adam Kaplan 🚌🚊🚢