In their 2016 developer survey, StackOverflow said poor documentation is the second-biggest problem faced by developers. 34.7% of respondents reported documentation as a challenge in their daily work. It’s not clear if that is internal documentation or upstream, but in either case the pain is largely self-inflicted.
Just as not everyone can write good code, not everyone can write good documentation. It’s a skill that requires practice, experience, and some talent. But the best documentation is what gets written. Documentation often has to start with the developer, even if someone else is responsible for cleaning it up.
The developer culture must embrace documentation. Test-driven development says write the tests first and code to the tests. Documentation-driven development is similar. We can argue about which should come first, but I’d suggest the documentation should inform the writing of the tests. Essentially, the documentation is the use case: the business reason you’re going to write code in the first place.
Writing documentation isn’t fun for a lot of people, so fostering a documentation culture is not easy. You can’t just say “thou shalt document” and expect it to happen. It has to be something you actively enforce. Your pull request doesn’t include documentation? It’s not getting merged until it does. You haven’t written a word of docs all year? No raise for you.
Once documentation takes root, though, it can be self-reinforcing. In the meantime, you do your users and your future self a big favor by making the effort now.