Stories
Slash Boxes
Comments

SoylentNews is people

Free Software is Suffering Because Coders Don’t Know How to Write Documentation

posted by n1 on Monday June 05 2017, @10:15AM   Printer-friendly
from the git-gud dept.

Arthur T Knackerbracket has found the following story:

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.
Free Software is Suffering Because Coders Don’t Know How to Write Documentation | Log In/Create an Account | Top | 88 comments | Search Discussion
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: 4, Insightful) by fraxinus-tree on Monday June 05 2017, @12:30PM (3 children)

    by fraxinus-tree (5590) on Monday June 05 2017, @12:30PM (#520685)

    I hate to say it, but a lot of them don't know how to write code, either.

    Starting Score:    1  point
    Moderation   +2  
       Insightful=2, Total=2
    Extra 'Insightful' Modifier   0  
    Karma-Bonus Modifier   +1  
    Total Score:   4  

  • (Score: 2) by turgid on Monday June 05 2017, @12:38PM (1 child)

    by turgid (4318) Subscriber Badge on Monday June 05 2017, @12:38PM (#520690) Journal

    Indeed, and that​ observation applies to software in general. 99% of programmers don't know how to write code. They're "unconscious incompetent." At least I'm "conscious incompetent" and trying hard to improve. Arrogance and hubris seem to be the order of the day. I weep for the future of the Human Race.

    • (Score: 0) by Anonymous Coward on Monday June 05 2017, @08:01PM

      by Anonymous Coward on Monday June 05 2017, @08:01PM (#520944)

      i can agree with this. i've been learning a language for a couple years(?) now and i can make things that that are well above my pay grade. i am well aware that i have much to learn but i can see evidence everywhere that many people think that they excrete petunias.

  • (Score: 2) by DannyB on Monday June 05 2017, @03:47PM

    by DannyB (5839) Subscriber Badge on Monday June 05 2017, @03:47PM (#520799) Journal

    These "learn programming in 24 hours" type books need to be: Learn to program in only ten years!

    It's not that you're not writing code right away. It's that you don't really know what you're doing. With experience comes the "what was I thinking when I wrote this?!?"

    --
    The thing about landline phones is that they never get lost. No air tag necessary.