Internal software documentation is often a controversial topic. Many developers avoid writing it and aim to produce just enough to get the project running. If you browse discussions on platforms like Reddit or Quora, most questions about documentation focus on why it's so poorly done or disliked by developers.
On the other hand, avoiding documentation slows down the team. It creates friction, forcing knowledge transfers to happen in person or requiring developers to reverse-engineer the code just to understand how to use it.
A few pain points make documentation as controversial as pineapple on pizza. Some people love it, others hate it. The goal of this article is to highlight what’s wrong with software documentation and suggest ways to improve it.
Developers Don’t See Immediate Value
Documentation doesn’t bring the same immediate value as shipping new features. There's often a lack of feedback, unlike the kind you get from users, and little recognition within the team for writing documentation. On top of that, documentation in any form can feel like unnecessary overhead. It's easier to justify spending time on high-quality code or thorough test coverage than on basic documentation that could aid future development.
Many developers haven’t yet felt the pain of bad documentation, so they don’t prioritize it. It is the leader’s responsibility to promote documentation by explaining its value and making it part of the team’s deliverables.
Developers Don’t Know What to Write
Most documentation doesn’t need a specific format or template. You simply write down everything you know about a piece of software, then add some headers to make it easier to read. This approach works well for most technical challenges in a project. However, if the topic is more complex and needs to be understood by teams beyond developers, then a more structured format is necessary. You can read about how I created a Design Doc that allowed me to win a new project.
Creating onboarding documentation requires structure because a new joiner can easily feel overwhelmed by too much information at once. Preparing the onboarding process and writing the supporting documentation isn’t easy, but I’ve shared my thoughts on onboarding documentation if you’re looking for some tips.
... continue reading