Ask Slashdot: What To Do About the Sorry State of FOSS Documentation? 430
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?
So fix it (Score:2, Interesting)
I document my findings on the Ubuntu wiki. If more people would take the hour to write up details on what they spent 2 weeks learning, we would all be better off for it.
A Wiki is not Documentation!!! (Score:2, Interesting)
In the past, there was usually a fairly good set of manual pages that seemed to accompany most OSS projects. However, nowdays all huge portion of projects seem to just think that if they set up a documenation wiki, they don't need to do anything else and some awesome documentation will just appear.
Yes! (Score:5, Interesting)
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:Read the source code (Score:4, Interesting)
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:It's open source (Score:4, Interesting)
I write code as a hobby and *gasp* I thoroughly document it, and in all fairness I don't do it for my customers (I have none) but for myself. I realized, couple decades ago, that if I don't comment my code it's a lot more difficult for me to remember what I did months or years later.
Comment removed (Score:4, Interesting)
I mail the author (Score:4, Interesting)
Then I hire him, after all writing code I accidentally use in my commercial product, and feeling being hold hostage because in a corner area it does not work, is his business model :)
Re:Yes! (Score:5, Interesting)
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.
How to fix the sorry state of FOSS docs (Score:4, Interesting)
Re:Nothing (Score:5, Interesting)
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?
Re:Nothing (Score:2, Interesting)
Including the foul language makes it very clear that the poster is biased, and can't (or won't) set aside that bias long enough to have a discussion.
My impression is that the writer sees his contributions as an altruistic gift that the programmers should be absolutely grateful to receive. Meanwhile, the programmer sees the documentation as just another aspect of the project, conveniently being handled by someone else.
Consider, then, a scenario where the programmer has implemented a function only enough to suit his needs, as for a library, but the writer wants to document every behavior of the function, as a writer should. At this point the writer asks the programmer to describe the complete behavior, but the programmer like can't, sa he hasn't defined or cared about behavior outside his necessary subset. This scenario, one of many with the same result, starts a disagreement where the writer expects more support from the programmer than the programmer is willing or able to provide.
Given the verbiage used in this post, we can infer how quickly a discussion about such a disparity of priority would heat up. I would not be surprised to learn that the writer had been dismissed from projects because of his attitude toward the programmers.
Teach, don't tell -- and the non FOSS world. (Score:3, Interesting)
First, I wanted to link to This blog post [stevelosh.com] by Steve Losh on writing documentation. I think offers some good metaphors as to why 'reading the source', even 'self documenting' source, is insufficient, though of course not everyone will agree with his philosophy.
Second, I wanted to say on the projects that I work on as a systems engineer doing new product development (as in this [wikipedia.org], not the information technology use of the term) documentation is perpetually threatened. And we usually work on comparatively well funded, non-FOSS programs. Documentation is timing consuming and expensive, and sometimes it is even customer direction to place it at a lower priority than new development. Though inevitably it makes things harder later, sometimes that is o.k. if it works better with the cash flow (saving money now only to pay more later can work if you expect to have more money later). Unfortunately FOSS software projects don't necessarily have people promising a ton of money for the documentation.
Re:Read the source code (Score:3, Interesting)
Yup, I'm convinced JavaDocs are the worst thing to happen to documentation in a long time. They actively discourage good documentation.
There is no good way to have API docs alongside meaningful documentation (with examples, diagrams, longer blocks of prose) without ramming everything into your codebase.
Look at Sphinx (Python's standard for docs - although supports other languages) - it allows you to curate custom docs, and then add in your API documentation from your code. Your code keeps it's core documentation for 'this is how you use this class/function', while your docs actually explain how the system fits together, how everything works.
JavaDocs are like a testing suite that only allows you to do unit tests - it makes you think in terms of the smallest unit, so you never test the whole. Sure, a foo may be passed into the bar, but what does that really mean? JavaDocs are essentially no more than browsing the code with folding enabled.
Good documentation is about all the stuff that *isn't* represented by your code. JavaDocs focus only on what is.
In general, Python is the best example - the documentation is execellent, and tools like DocTests allow you to ensure your documentation is up to date and accurate.