61–70 of 153 posts
Done right, it’s the final abstraction to the code: The whys and the hows, and effectively and gently guides the developer from epic/functional/spec/user requirements to the underlying design & implementation.
And by god, less is more; and more maintainable.
Although I do agree that it is vastly underappreciated :/.
It'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.
It works. But it's hard to be consistent.
Let's say someone build a great feature with a lot of traction (e.g. money) but no doc.
Will you punish the team or celebrate the success?
"Sorry, your project make 20m, higher than any other projects in the company, but your doc is bad, so... you get below expectation rating this time".
There are tons of successful software with very little doc. So, my imaginary situation is very plausible. On the other hand, bad software with good doc rarely succeeds. But tbf bad software means unsuccessful software....
I 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…
My manager uses a template to create JIRA tasks - it makes it short and to the point. Just a handful of questions like Who needs it? what needs to be done? who is the subject matter expert? and so on. This makes it easier for the developer working on the task, keeps the description short and sweet.
Recent example: https://libguestfs.org/nbdfuse.1.html
I 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.
I 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.
Hire 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.