6 ms·

Ask HN: How do you motivate developers to write documentation?

I'm a junior developer currently working on a knowledge base for developers at the company I work at. I've set up most of the KB features but then it hit me: Why would anyone use this? There are countless other existing solutions that they're not using anyway, what makes mine different? I've thought of focussing on the motive; to give the developer a reason to write documentation. One the ideas was to have organizing workshops to be the center of the KB. Workshops would require research which would be the documentation. Past workshops could then be used to store related documentation. What are other activities, interests that could motivate developers to write documentation?

patrick451 5y ago
Just like comments, documentation is a code smell. Too much documentation is an indication that your codebase is in need of a major overhaul.
- shoo 5y ago
  documentation can be invaluable when it explains the underlying requirements or constraints behind a particular implementation. if you can just see the implementation but have no documentation of what the actual requirements and constraints are, what problem is trying to be solved, there's no way to evaluate if the code is correct or not, even if the code is structured in a way that looks subjectively clean, elegant, performant, etc. if the codebase is super elegant but is solving a problem that is no longer relevant to the organisation, the correct move is likely to delete or archive the repo and avoid the ongoing cost of maintaining it. if you are new to a codebase and look at a particular implementation of something without any context, maybe it looks very strange and should "obviously" be refactored to align more with some standard application design principle or heuristic. but without the extra context of "oh originally it was written the standard way but for operational / business reasons X Y Z we had to contort it this way to avoid causing production outages due to interactions with bugs in the A B C layer" or "oh that was written by a contractor in a hurry who we got rid of for underperforming, yeah there's no reason it had to be that way, cleaning it up is on the backlog when we next have a reason to touch that part of the code" you're operating blind.
pacifika 5y ago
I write documentation to make onboarding easier. End user documentation is usually written by developers to ease the support burden.
- aromaticbanana 5y ago
  Do you insert the documentation in some sort of onboarding program? I've seen some solutions that have some gamification elements that have a motivating effect to the user [0][1]. [0] https://www.producthunt.com/posts/user-onboarding-checklists-by-appcues https://www.producthunt.com/posts/user-onboarding-checklists... [1] https://www.producthunt.com/posts/rippling-peo https://www.producthunt.com/posts/rippling-peo
- mateo411 5y ago
  Our onboarding documention is decent, but it's usually a little bit out of date. I have the person who is being onboarded update the documentation.
Leftium 5y ago
I think documentation has to be tied to performance evaluation/salary, or at least not hinder your performance. I worked at a large, well-known software company. There were very few comments documenting the code. Aside from the auto-generated comments based on function declarations, there wasn't much (any?) documentation. I figured a big reason for this was people were paid/rewarded based on the number of bugs that they fixed, not on how much documentation was produced or other people helped.
karmakaze 5y ago
> What are other activities, interests that could motivate developers to write documentation? This is the wrong way of looking at it. It assumes a premise that documentation is a goal rather than a means. To get developers to write documentation there's a few key ingredients. It has to deliver value that the writers appreciate. It has to keep delivering value over long time periods (e.g. stale docs can sometimes be worse than no docs). There has to be a culture/routine of writing documentation and kept as a priority so that it doesn't get cut when there's a time crunch or other work priorities. Oh yeah one other huge one is that it has to have minimal friction: e.g. commit it in the repo with the code changes so that it's no extra steps and the doc changes get reviewed with code changes.
- tra3 5y ago
  Well said. It’s similar to automated testing. We all agree it’s a must. Lots of hand waving around how important it is, and everyone agrees! I’d say that about 50% of the projects that I’ve been on lacked automated testing. For reasons. I’d say documentation is in the same limbo. We as an industry lack maturity and motivation when it comes to delivery.
tomjen3 5y ago
I am not a native English speaker, but even in my native language I am terrible at spelling. Somewhat better at grammar. However I feel that I was to write documentation for something I would just have a bunch of annoying nitpickers. I would be far more willing to write documentation if it was for a pleasant to use wiki, where nothing was ever supposed to be finished, only improved: I would not feel pressure to be perfect, there would be no pressure to be complete (I can start out by just dumping my notes) I could get a nice dopamine hit by helping somebody. I don't think a workshop would be helpful at all (is hurtful an English word?), not only would it be something that is not programming or being social (ie something that I would prefer not to attend), and I think you underestimate how much work there is in organizing it.

patrick451 5y ago

Just like comments, documentation is a code smell. Too much documentation is an indication that your codebase is in need of a major overhaul.

shoo 5y ago
documentation can be invaluable when it explains the underlying requirements or constraints behind a particular implementation. if you can just see the implementation but have no documentation of what the actual requirements and constraints are, what problem is trying to be solved, there's no way to evaluate if the code is correct or not, even if the code is structured in a way that looks subjectively clean, elegant, performant, etc. if the codebase is super elegant but is solving a problem that is no longer relevant to the organisation, the correct move is likely to delete or archive the repo and avoid the ongoing cost of maintaining it. if you are new to a codebase and look at a particular implementation of something without any context, maybe it looks very strange and should "obviously" be refactored to align more with some standard application design principle or heuristic. but without the extra context of "oh originally it was written the standard way but for operational / business reasons X Y Z we had to contort it this way to avoid causing production outages due to interactions with bugs in the A B C layer" or "oh that was written by a contractor in a hurry who we got rid of for underperforming, yeah there's no reason it had to be that way, cleaning it up is on the backlog when we next have a reason to touch that part of the code" you're operating blind.

pacifika 5y ago

I write documentation to make onboarding easier. End user documentation is usually written by developers to ease the support burden.

aromaticbanana 5y ago
Do you insert the documentation in some sort of onboarding program? I've seen some solutions that have some gamification elements that have a motivating effect to the user [0][1]. [0] https://www.producthunt.com/posts/user-onboarding-checklists-by-appcues https://www.producthunt.com/posts/user-onboarding-checklists... [1] https://www.producthunt.com/posts/rippling-peo https://www.producthunt.com/posts/rippling-peo
mateo411 5y ago
Our onboarding documention is decent, but it's usually a little bit out of date. I have the person who is being onboarded update the documentation.

Leftium 5y ago

I think documentation has to be tied to performance evaluation/salary, or at least not hinder your performance. I worked at a large, well-known software company. There were very few comments documenting the code. Aside from the auto-generated comments based on function declarations, there wasn't much (any?) documentation. I figured a big reason for this was people were paid/rewarded based on the number of bugs that they fixed, not on how much documentation was produced or other people helped.

karmakaze 5y ago

> What are other activities, interests that could motivate developers to write documentation? This is the wrong way of looking at it. It assumes a premise that documentation is a goal rather than a means. To get developers to write documentation there's a few key ingredients. It has to deliver value that the writers appreciate. It has to keep delivering value over long time periods (e.g. stale docs can sometimes be worse than no docs). There has to be a culture/routine of writing documentation and kept as a priority so that it doesn't get cut when there's a time crunch or other work priorities. Oh yeah one other huge one is that it has to have minimal friction: e.g. commit it in the repo with the code changes so that it's no extra steps and the doc changes get reviewed with code changes.

tra3 5y ago
Well said. It’s similar to automated testing. We all agree it’s a must. Lots of hand waving around how important it is, and everyone agrees! I’d say that about 50% of the projects that I’ve been on lacked automated testing. For reasons. I’d say documentation is in the same limbo. We as an industry lack maturity and motivation when it comes to delivery.

tomjen3 5y ago

I am not a native English speaker, but even in my native language I am terrible at spelling. Somewhat better at grammar. However I feel that I was to write documentation for something I would just have a bunch of annoying nitpickers. I would be far more willing to write documentation if it was for a pleasant to use wiki, where nothing was ever supposed to be finished, only improved: I would not feel pressure to be perfect, there would be no pressure to be complete (I can start out by just dumping my notes) I could get a nice dopamine hit by helping somebody. I don't think a workshop would be helpful at all (is hurtful an English word?), not only would it be something that is not programming or being social (ie something that I would prefer not to attend), and I think you underestimate how much work there is in organizing it.