Stories
Slash Boxes
Comments

SoylentNews is people

SoylentNews is powered by your submissions, so send in your scoop. Only 17 submissions in the queue.

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: 2) by Zyx Abacab on Monday June 05 2017, @06:49PM (4 children)

    by Zyx Abacab (3701) on Monday June 05 2017, @06:49PM (#520897)

    Then again, neither vim nor emacs is only a text editor. One is a programmable command environment, and the other is almost a full-fledged OS; in either one, the text-editing functionality is merely a coincidence.

    Starting Score:    1  point
    Karma-Bonus Modifier   +1  
    Total Score:   2  

  • (Score: 2) by tangomargarine on Monday June 05 2017, @06:55PM (3 children)

    by tangomargarine (667) on Monday June 05 2017, @06:55PM (#520902)

    in either one, the text-editing functionality is merely a coincidence.

    That requires a certain perspective to get there. On a descriptive level, that may be what they are now, but the fundamental purpose was always to be a text editor. And I would argue the raison d'être can't be a coincidence, by definition.

    --
    "Is that really true?" "I just spent the last hour telling you to think for yourself! Didn't you hear anything I said?"

    • (Score: 2) by FatPhil on Tuesday June 06 2017, @07:28AM (2 children)

      by FatPhil (863) <{pc-soylent} {at} {asdf.fi}> on Tuesday June 06 2017, @07:28AM (#521214) Homepage
      a legacy feature, then?
      --
      Great minds discuss ideas; average minds discuss events; small minds discuss people; the smallest discuss themselves

      • (Score: 2) by tangomargarine on Tuesday June 06 2017, @02:42PM (1 child)

        by tangomargarine (667) on Tuesday June 06 2017, @02:42PM (#521336)

        If by "legacy feature" you mean "something I still use on a daily basis in a non-ironic fashion," I guess.

        - a 27yo emacs user

        --
        "Is that really true?" "I just spent the last hour telling you to think for yourself! Didn't you hear anything I said?"

        • (Score: 2) by FatPhil on Wednesday June 07 2017, @08:21AM

          by FatPhil (863) <{pc-soylent} {at} {asdf.fi}> on Wednesday June 07 2017, @08:21AM (#521808) Homepage
          Ditto. And quite literally ditto - my 1st real emacs use was 1990 too.
          (I had uEmacs on my Atari ST a year or two before that.)
          --
          Great minds discuss ideas; average minds discuss events; small minds discuss people; the smallest discuss themselves