By far the most frequent user of the documentation I wrote was ... I again, but two to ten years down the line.
It was still worth it.
Why programmers don’t write documentation
51–60 of 153 posts
Re: Why programmers don’t write documentation
#52It's not rewarded and recognized. Good software, bad doc is probably okay. Bad software, good doc is downright bad. Therefore, people/exec/management don't prioritize it. If it were to be compensated with 100k, you would get the best doc ever. We can't improve things if we don't incentivize. We don't incentivize because it's not that important.
What if we don’t incentivize and it’s important? Further, what if we can improve it without incentivizing? My teams code is very well documented because we encourage documentation during code review. No one gets a bonus for this, but it doesn’t matter because we care about our softwares quality. Put another way, good software bad doc is a lot harder and more costly than good software good doc.
Your team is incentivizing it during code review.
Re: Why programmers don’t write documentation
#53Documentation is so important. The problem with documentation is that engineers don't seem to understand it's benefits. I think one reason is that so much of the documentation out there is so poor quality that engineers think documentation can't be good quality.
Ding ding ding ... you summarized most of the reasons why but your conclusion is wrong. What does not and likely cannot exist is not important.
Re: Why programmers don’t write documentation
#54Earlier quoted context omitted.
This was my attitude as well for much of my career, and it was a mistake. The "correct" decision depends on the state of the business and your resources at the time. And nothing else.
Yes, I've worked mostly in money losing startups, but since I work in a $ billion-profit investment bank I saw the difference. It's better to waste money on technical debt crisis down the line than have no money to waste because of thousands of devs all being perfectionists locking each other. Small startups seem to reach this stage eventually and in big companies, management is acutely aware of it, and breaks every…
So much matches with my experience. This is an indication of which company will survive two years down the lane and which not.
Too much perfectionist? You will enjoy the journey, but probably won't reach your destination.
Re: Why programmers don’t write documentation
#55I wrote a whole Twitter thread a while back on this very topic: https://twitter.com/alexpotato/status/1224309861304938496 The single biggest ROI I've seen on getting documentation written is to provide a template for developers to fill out. Blank wiki pages are incredibly intimidating and developers can't always anticipate what people will want. Having a "madlib" style outline with things like: - Where does this app…
This. Some of the best documentation is a simple "getting started" guide that explains: How to build (any dependencies?), how to hook a debugger or access debug logs and some pointers to where to start when looking at code (example: set a breakpoint here and trigger this action, you'll end-up in X component and should be able to figure out what's going on from there).
Re: Why programmers don’t write documentation
#56I do both and it’s not hard, it’s work and people have gotten lazy and don’t do work anymore they just write and read BS on the net and call it true and vote people down for telling the truth.
Re: Why programmers don’t write documentation
#57The single best thing you can do for good documentation is to hire actual technical writer. Someone who already knows how to write in general, how to write and structure technical texts specifically and who wants to write.
It has three advantages:
- They are cheaper then programmers.
- They write faster then programmers.
- Unlike programmers, they produce well structured easy to read text.
And bonus: if you are lucky, they will be able to explain to programmers how to write better. They won't make them into James Joyces, but will make them learn a bit. It will take time and only some programmers will improve, but the technical writers has that effect.
Re: Why programmers don’t write documentation
#58Hire a technical writer. Not only for your external documentation... for all of it. If you are afraid of the costs, do the math. 1 technical writer for every 20 developers.
100% this.
Re: Why programmers don’t write documentation
#59I do both and it’s not hard, it’s work and people have gotten lazy and don’t do work anymore they just write and read BS on the net and call it true and vote people down for telling the truth.
Lazy? Where I'm from we call it agile. You know. Scrum and stuff.
Re: Why programmers don’t write documentation
#60I do both and it’s not hard, it’s work and people have gotten lazy and don’t do work anymore they just write and read BS on the net and call it true and vote people down for telling the truth.
If it was easy lazy people would do it, just like they write code.