Comment by GarnetFloride
2 days ago
Yeah. Being a tech writer is tough because few people appreciate the work.
But the things I really need from devs is what is the feature supposed to do and why did you do it that way?
I can read the code to know what it does but often that’s not what it’s supposed to do.
The why can be simple too. We had a dev write an archive delete function that failed but the way was because the CEO pressured him.
I’d love to know what you think documentation means.
The "why" can be so important... like you said, I can read the code, but I can't always divine the original author's intents...
Anecdote:
I once (well, many times, but especially this one time) inherited a completely undocumented codebase from a previous "lone wolf", mad genius type of programmer. Most of the stuff he wrote was completely inscrutable at first but really kinda genius once you figured it out.
But one day I was tweaking one of his heatmaps showing solar production on a rooftop from "off" to "a little" to "a lot" to "this is broken", and his color gradient code was a magical one-liner doing strange math as hex operations. It usually went from blue to red to yellow, but would sometimes "overflow" into other strange colors that made no sense. I spent a few hours simulating different edge cases and getting back colors I could not reasonably explain — and which would confuse our users. I talked to my coworkers about it, who mostly insisted "Well, I don't know, but he was a very smart guy, so we should probably just trust him and move on". That was unsatisfying, and didn't really help me close the customer ticket that I was trying to solve.
I kept bugging my boss about it, and after a few days of back and forths and seeing my simulation, he finally agreed to let me reach out to the original programmer (who had long since left the team). I finally got my answer a few hours later. He said, "Oh... that was just some random throwaway gradient I thought looked pretty, lol. I was lazy and wrote it in a hurry and, yeah, it probably bugs out on all but the simplest cases, and doesn't conform to any color standards... glad he caught it."
Sigh, lol... that took several person-days to resolve, when it could've been a simple // #TODO: Use a better gradient system someday
> I’d love to know what you think documentation means.
I'd say effective documentation lets the user know enough about the system that they can work on the system without needing to contact the previous person (or people) working on the system. Or at least, so they can get started and only ask 'good' questions.
Something like descriptions of what the system is supposed to do, what it actually does if it differs significantly :D, maybe motivations. Descriptions of the data, and like where does it come from, where does it go, where did it come from (Cotton-Eye Joe?). If the system runs into problems often, a list of common issues and how to fix them, etc.