There seems to be an aversion to writing even the most basic documentation. Our project READMEs are relatively bare. There aren't even updated lists of dependencies in the docs.Is there something I'm unaware of in the industry that makes programmers dislike writing documentation? I can type out paragraphs of docs if needed, so why are others so averse to it?More importantly, how do I convince them that writing docs will save us time and frustration in the future?
What's with the aversion to documentation in the industry?
documentation;teamwork
I don't think it's helpful to speculate on the motivations of people who aren't adopting something you think is good practice or who are continuing to do something you see as bad practice. In this business, the people who fall into one or both of those categories will far outnumber the ones who you'll see eye-to-eye with, so stop making yourself crazy.Instead, focus on the problem and possible resolutions.1. Write Good Documentation YourselfIt may not be realistic to expect that everyone on your team will direct their efforts to the things you see as a problem. This is especially true if you're a relative newcomer to the team. I'd venture to guess that you are, because if you were a founding member of the team, it seems quite likely you'd have already resolved this issue early on.Consider, instead, working toward the goal of writing good documentation yourself and getting people to use it. For example, if someone on my team asks me where the source code for Project A is or what special configuration Project A needs, I point them to the Project A wiki page.If someone asks me how to write a new implementation of Factory F to customize a thing for Client C, I tell them it's on page 10 of the developer guide.Most developers hate asking questions that could make them look like they can't just read the code even more than they hate reading documentation, so after enough replies of this nature, they will go to the docs first.2. Prove the Value of Your DocumentationMake sure that you take every opportunity to point out where the documentation is proving its value (or would have, if used). Try to be subtle and avoid I told you so, but it's perfectly legitimate to say things like For future reference, the wiki page of this project has information about the branch of the core code that was created for ongoing support of release 2.1, so in future we can avoid having to do a full regression test if people who are maintaining released versions check the wiki before checking out the code. or I am so glad I wrote down the steps for doing Task T. I don't really care if no one else ever uses it--it's already saved me more time than what I spent writing it.3. Get Management on BoardAfter a few incidents where having documentation is provably saving time/money, you'll probably notice a distinct thaw toward documentation.  This is the time to press the point by starting to include documentation time in your estimates (though honestly I usually update/create docs while long processes are running, such as compiles or check-ins). Especially if this is a recent hire, it's possible this won't be questioned, but instead viewed as a new practice you're bringing in from a previous workplace (which it may well be).Word of caution: Most bosses don't like to make people do anything, especially things not directly tied to a billable task, so don't expect this support to be in the form of a mandate. Instead, it's more likely to give you relatively free rein to write more docs.4. Encourage Documentation When You See ItMaybe part of the reason people don't write docs as often as they should is they feel no one is reading it. So, when you see something you like, make sure to at least mention that you were glad it was available.If your team does code reviews, this is a time where you can drop in a subtle word or two to encourage good comments. Thank you for documenting the workaround for bug B in Framework G. I didn't know about that, and I don't think I could have understood what you were doing without that in there.If you have someone on the team who's actually enthusiastic about documentation, it doesn't hurt to cultivate that person through going to lunch or coffee and making sure to offer a little validation to counteract the discouragement they may get from seeing the rest of the team doesn't value the documentation as much.Beyond that, it's really not your problem unless you're in a lead or management position. You can lead a horse to water, but you can't make it drink. If it's not your horse, you might not be happy that it's thirsty, but all you can do is fill the trough.