Self-employed guy who likes to help people and sometimes that means building a website. Ex-college professor. Ex-streaming media guy. Ex-LMS admin. Ex-Performance Support Consultant. Likes beer.
I've probably written 20 versions of this comment and then deleted them, illustrating better than anything else the challenges of any writing. Documentation is a big, huge, gigantic ball of pain and suffering that's great when it works and death by a thousand paper cuts when it doesn't.
To me, the best documentation has a point. There's a reason it's there. It tells me what that reason is right up front, then, in the fewest words possible, it actually does that thing. Then it stops.
It's easier said than done, of course. It's about as much practical use as the old joke: "Want to be a millionaire? Great. First, get a million dollars..."
I never really spent that much time on documentation because the thing most students had a good grasp on was "I don't want to be here and I'm afraid of making a mistake and looking dumb."
When I had to write multiple-choice test questions I always made the last choice a joke answer because test anxiety is a real thing and I figured if I could get them laughing it might make them forget to be nervous. After a while I just sort of extended that into all of my teaching. And so it snuck into my writing.
I prefer the joke "How do you get a small fortune?" Start with a large one.
Yes, documentation is hard, often harder than writing code. What does this do? What are the restrictions on arg x? Where does this method fit in a workflow?
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
First off, thanks.
I've probably written 20 versions of this comment and then deleted them, illustrating better than anything else the challenges of any writing. Documentation is a big, huge, gigantic ball of pain and suffering that's great when it works and death by a thousand paper cuts when it doesn't.
To me, the best documentation has a point. There's a reason it's there. It tells me what that reason is right up front, then, in the fewest words possible, it actually does that thing. Then it stops.
It's easier said than done, of course. It's about as much practical use as the old joke: "Want to be a millionaire? Great. First, get a million dollars..."
I never really spent that much time on documentation because the thing most students had a good grasp on was "I don't want to be here and I'm afraid of making a mistake and looking dumb."
When I had to write multiple-choice test questions I always made the last choice a joke answer because test anxiety is a real thing and I figured if I could get them laughing it might make them forget to be nervous. After a while I just sort of extended that into all of my teaching. And so it snuck into my writing.
I prefer the joke "How do you get a small fortune?" Start with a large one.
Yes, documentation is hard, often harder than writing code. What does this do? What are the restrictions on arg x? Where does this method fit in a workflow?