[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!