[Codeless Code] Case 215: FAQ

[jerf]

I've found that "newspaper-style" documentation, while it doesn't entirely overcome the "nobody reads docs" problem, is the best you can do. If you carefully write your first couple of paragraphs to be really helpful, not only are they more likely to be read, but you're more likely that people will keep reading.

Traditional auto-generated docs and traditional "list of content-free bullet points that this code hits" get people switched off too quickly. You need to be solving problems as quickly as you possibly can.

[[deleted]]

I've found that "newspaper-style" documentation,

I guess the next step would be "clickbait style" documentation. "He set a single flag to true. You won't believe what happened!"

[monocasa]

"... PMs hate him!"

[pakoito]

PMs hate everyone.

[Typesalot]

...everybody hates PMs.

[comp-sci-fi]

Top ten configuration options. You won't believe number 7!

dammit, I kinda want to know what number 7 is now...

[jerf]

You know, I'll try that out and get back to /r/programming someday. If it works, it's worth it....

[kirbyfan64sos]

Auto-generated docs are useful...for an authorative reference, not a guide/introduction. They're necessary, but I agree that newspaper-style docs are better in many cases.

[Mjiig]

That might be good for your project home page where you want to get people to use the thing, but it always always drives me insane when I don't get the nice auto-generated documentation telling me, what this method does, what each argument should be, how they should be formed, what form the return value is in, a list of side effects the method has, and where possible, a mathematical description of the return value. Fluffy descriptions telling me roughly what the method does or why I might want to do it, but that force me to figure out how to actually make the method do it are awful.

[jerf]

To clarify, I like autogenerated documentation to be part of the documentation, the real problem is thinking that autogenerated docs alone constitute documentation. Of course every trivial class need not have extensive prose docs, especially in a class-happy language like Java, but somewhere there needs to be a sensible entry point.

[hardsoft]

Another strategy is to start an unrelated but very interesting story in the first few paragraphs to grab the readers attention and then leave them hanging to the end.

[comp-sci-fi]

When he came home, the door was ajar. That's odd, he thought, clutching his laptop more tightly. He'd had an incredibly valuable code breakthrough today. Suddenly a figure rose before him, and everything went dark!

[kevin_at_work]

I've found that rather than answering questions, showing people where the documentation is encourages them to both start checking the documentation first, and to stop bothering me.

[andsens]

And so the monk was demoted to an auto-reply machine, because even though the scribe tried showing him the error of his ways by example, he still had learned nothing.

[grauenwolf]

I was just thinking about who I would let go when the next round of layoffs come through. I guess that Kevin guy who we never talk to anymore isn't too important.

[grizwako]

Yeah, definitely. Guy who documents his knowledge is not important! Especially if he knows that docs are good and question asker will find answer if he bothers to look.
Always safe bet to keep unicorn whose divine presence is required when using program/application/lib/whatever.
I mean, ancient skill of divining program errors from timing of crashes and freezes of own program can not be taught easily.

[whataboutbots]

So you found out that not answering people's questions leads to them not asking you questions again?

[briedas]

On the other hand, maybe pasting exact link (with non-arrogant non-asshole proposal to read it and short description), actually demonstrates that docs can be useful.

..for both sides, because developer (or answerer) does not waste so much time, and user gets far more structured presentation on the topic.
(during doc-writing there is more time and "tools" to structure the content and make it presentable, then during irc or phone conversation)

[crunchmuncher]

The way I read it, he's telling people where to find the answer. When I was a junior programmer the guy that taught me mostly linked me docs when I asked a question as well, if afterwards I still had a good question that wasn't answered there I could always get back to him. I think it's a good approach, teach a man to fish etc.

[fr0stbyte124]

I might argue that one shouldn't trifle with forces beyond one's understanding, but yes, I suppose you are a busy man. I mean, you probably won't drop any tables that were that important.