Stories
Slash Boxes
Comments

SoylentNews is people

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: 1, Interesting) by Anonymous Coward on Monday June 05 2017, @03:16PM (1 child)

    by Anonymous Coward on Monday June 05 2017, @03:16PM (#520780)

    Before it was called "Gonzo" there was Normal Mailer's "The Naked and the Dead" -- this sets a very high bar for the "hyper-realistic war documentary fiction" category, which I believe Mailer invented(?), although in other writings Mailer says that he was inspired by Faulkner...

    Tom Wolfe and Hunter Thompson surely read Mailer when they were starting out.

    ---
    > flash drive he was holding seemed to change shape into a frog and hopped away

    This reminded me of a trippy college evening. I got back to the co-op where I was living and discovered that it was my day for kp. Had to wash the dishes for 30 people, while the dishes were grinning at me and and trying to jump out of my hand and onto the floor. I focused hard and none of them escaped!

    Starting Score:    0  points
    Moderation   +1  
       Interesting=1, Total=1
    Extra 'Interesting' Modifier   0  

    Total Score:   1  
  • (Score: 2) by VLM on Monday June 05 2017, @03:41PM

    by VLM (445) Subscriber Badge on Monday June 05 2017, @03:41PM (#520795)

    Normal Mailer's "The Naked and the Dead"

    Interesting I donno how I missed that book...

    I'm very familiar with Leckie "Helmet for my pillow" and Sledge "With the old breed" and its interesting they didn't write their books until decades after the war.

    A lot of gonzo seems to be of the "alienated journalist is LARPing as not really a journalist not really a participant and high on drugs most of the time", I wouldn't say "Dispatches" is very realistic portrayal of life as either a REMF or a front line grunt, its a realistic portrayal of kind of a journalist/tourist. Toward the end of "Dispatches" the author gets super alienated because he's not even a real journalist because he's writing for a monthly magazine and "real" journalists either write for daily newspapers or are weekly photojournalists so he spent an inordinate amount of time baking and goofing off. I kind of like the book "Dispatches" but I get the feeling the author himself is (or at least was as a kid) a degenerate piece of shit, none the less with some writing skill.

    Now, Sledge and Leckie were front line grunts, and tell quite a story. Also they're likable unlike the poseurs Thompson and the "Dispatches" author.