Ask Slashdot: What To Do About the Sorry State of FOSS Documentation?

First time accepted submitter TWX writes I've been out of computers as a serious home-hobby for many years and in returning I'm aghast at the state of documentation for Open Source projects. The software itself has changed significantly in the last decade, but the documentation has failed to keep pace; most of what I'm finding applies to versions long since passed or were the exact same documents from when I dropped-out of hobbyist computing years ago. Take Lightdm on Ubuntu 14.04 for example- its entire configuration file structure has been revamped, but none of the documentation for more specialized or advanced uses of Lightdm in previous versions of Ubuntu has been updated for this latest release. It's actually harder now to configure some features than it was a decade ago. TLDP is close to a decade out-of-date, fragmentation between distributions has grown to the point that answers from one distro won't readily apply to another, and web forums for even specific projects are full of questions without answers, or those that head off into completely unrelated discussion, or with snarky, "it's in the documentation, stupid!" responses. Where do you go for your FOSS documentation and self-help?

Comments

Yes!

[war4peace]

I am saddened to say that the lack of proper, structured documentation, combined with bad experience every time I asked a question on OFSS forums kept me away from OFSS in general (and Linux, more specifically). Every year I try again and I am seeing the same results.
I know I might ask questions perceived as "stupid" but everyone's been a newbie at some point in time. Maybe it's just my turn to be one. Thing is, once I get the correct, detailed answer I never ask the same question again but I almost never get the answer, just "RTFM" and "haha noob" with the obligatory variations.

Of course, I've been trying to ask very specific questions, I've provided detailed information on my issue and was very polite myself. Still was met with smug and bile.

In all fairness, creating documentation is something that almost nobody wants to do. I get that. However, politely answering a question shouldn't be that difficult.

Re:Yes!

[war4peace]

True words, I've seen people who behaved like that.
Here's a funny story that I was involved in a couple years ago.

My desk was at the time located on a developer-heavy floor, very silent, with everybody neck-deep into their code. They generally regarded me as "the uninitiated", treating me with contempt, at most. Hardly ever anyone talking to me. Two developers were sitting across my desk and they were smokers, so we occasionally ended up on the balcony together. One day, they were talking about an application UI bug which they were trying to fix. I, as a non-developer, was ignored, of course, but I was shamelessly eavesdropping in the hopes I would learn something from their... um, well, gibberish (of sorts). The UI bug was around some fields not being populated automatically when values were selected in others. Think of it as a chain of picklists with dynamically populated List-Of-Values.
I gathered my strengths and asked them whether it could be the fact that some picklists are populated in the wrong chronological order. They looked at me in a weird way, said nothing, then thrown their cigarette butts and went inside. I felt like a kid asking "Mooom, what's a dick?" during Uncle Moke's funeral.
Couple hours pass and they come to me and ask me whether I would join them for another cigarette. I was very much surprised. On the balcony, they told me I was actually right and the bug was fixed.
Glad I could help.
They respected me and talked to me a lot more after that, and I helped them crush a few more bugs by just listening to them while they explained what was wrong and brainstorming what might cause it. We still keep in touch even if they moved to a different company.

While the above wall of text is a bit offtopic, the idea is that if a developer treats everyone else as if they are no good, he might miss opportunities.

Re:Read the source code

[james_pb]

This is silly. I've been trying to use Autodesk Fusion 360 - it's most definitely a proprietary bit of software from a large developer.

The documentation is worse than awful; you'd be better off just reading the source.

And iOS vs Android? iOS is pain layered on suffering. Reading the source would be _so_ much better than depending on Apple.

Commercial != good doc.

Re:Nothing

[Bob9113]

MOTHERFUCKER, IT DOESN'T WORK LIKE THAT. Fuck you in your goddamn asshole you fucking arrogant fucking pricks...The fact of the matter is the majority of programmers are assholes that have no business operating in normal society. Lock them in the fucking closet and let them read the fucking source until they jizz all over their crusty beards while fantasizing about Stallman's brown pucker.

Just a wild guess here, but hear me out: Is there any chance that your interpersonal skills could have contributed to the lack of communication?