Slash Boxes

SoylentNews is people

SoylentNews is powered by your submissions, so send in your scoop. Only 15 submissions in the queue.
posted by n1 on Monday June 05 2017, @10:15AM   Printer-friendly
from the git-gud dept.

The Open Source Survey asked a broad array of questions. One that caught my eye was about problems people encounter when working with, or contributing to, open source projects. An incredible 93 percent of people reported being frustrated with “incomplete or confusing documentation”.

That’s hardly a surprise. There are a lot of projects on Github with the sparsest of descriptions, and scant instruction on how to use them. If you aren’t clever enough to figure it out for yourself, tough.

[...] According to the Github Open Source Survey, 60 percent of contributors rarely or never contribute to documentation. And that’s fine.

Documenting software is extremely difficult. People go to university to learn to become technical writers, spending thousands of dollars, and several years of their life. It’s not really reasonable to expect every developer to know how to do it, and do it well.

2017 Open Source Survey

-- submitted from IRC

Original Submission

This discussion has been archived. No new comments can be posted.
Display Options Threshold/Breakthrough Mark All as Read Mark All as Unread
The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
  • (Score: 2) by VLM on Tuesday June 06 2017, @03:48PM

    by VLM (445) on Tuesday June 06 2017, @03:48PM (#521377)

    In theory true but even if generally true there's a spectrum of it and Cisco for example used to have legendary good docs online AND I was personally involved at a company where Cisco Certs meant a price deduction on the huge bill, a deduction big enough that paying me to shitpost and play video games all day would still have been a net profit to the company. Of course rather than shitpost and video I got stuck providing BGP support to our customers, which I was very good at although it got boring after the 50th time some guy tried to send us a 0/0 route or wanted to advertise his previous ISP's subnet, LOL. "Well see I was tryin to redistribute my RIP routes into BGP" "Excuse me sir WTF are you doing, STFU and configure it the way I tell you to" (although I spent about four hours per customer or so it seemed doing it very politely, although the previous one liner summarized it remarkably well). I also felt like a hostage rescue negotiator some days "I see my routes are dampened because of flapping, what does that mean, I guess I'll go reboot my router a couple times till it starts working again" "nooooooooo nooooo don't jump your router has a lot to live for nooooooo"

    Starting Score:    1  point
    Karma-Bonus Modifier   +1  

    Total Score:   2