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: 2, Informative) by Anonymous Coward on Monday June 05 2017, @10:29AM (9 children)

    by Anonymous Coward on Monday June 05 2017, @10:29AM (#520658)

    It's not even that they don't know. It's just almost nobody wants to.

    Starting Score:    0  points
    Moderation   +2  
       Insightful=1, Informative=1, Total=2
    Extra 'Informative' Modifier   0  

    Total Score:   2  
  • (Score: 4, Interesting) by The Mighty Buzzard on Monday June 05 2017, @10:55AM (3 children)

    Yup. It's pulling teeth to get anyone on staff except audioguy to even document our own setup. Yes, this includes me.

    --
    My rights don't end where your fear begins.
    • (Score: 2) by JoeMerchant on Monday June 05 2017, @01:13PM

      by JoeMerchant (3937) Subscriber Badge on Monday June 05 2017, @01:13PM (#520707)

      Documentation is a thankless job - you do a great job of documenting the existing setup, then the coders and testers change it all and your documentation is broken, but nobody cares enough to help you fix it.

      Autogenerated documentation like doxygen at least moves the problem closer to the source... still impossible to get coders to slow down and update the comments even when they're right there in the header of the subroutine, but when it's broken, the git-blame function at least gives you a name to go after to try to get some "what the hell were you thinking here" to go with the obvious stuff.

      --
      Україна досі не є частиною Росії.
    • (Score: 0) by Anonymous Coward on Monday June 05 2017, @01:39PM

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

      It's the least fun part of your job. I barely do it when they pay me, why do it for free?

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

      by Anonymous Coward on Monday June 05 2017, @02:38PM (#520756)

      I would love to write documentation if someone payed me to do it.
      but I'm actually payed for running the code I write and analyzing the results.

  • (Score: 2) by driverless on Monday June 05 2017, @11:31AM (4 children)

    by driverless (4770) on Monday June 05 2017, @11:31AM (#520672)

    Yup. I went to a talk about a decade ago that compared OSS to commercial software development, and one of the points they made was that in a commercial environment you get (mostly) decent documentation because you can pay someone to do it. In addition because you've got paid features in your product you want your customers to know they're there and how to use them, so they need to be fully documented.

    Without that financial incentive, documentation is treated as job #37. Or as they put it, "everyone wants to be a code god, no-one wants to be a documentation god".

    • (Score: 2) by aristarchus on Monday June 05 2017, @05:08PM (3 children)

      by aristarchus (2645) on Monday June 05 2017, @05:08PM (#520840) Journal

      one of the points they made was that in a commercial environment you get (mostly) decent documentation because you can pay someone to do it.

      Except that with commercial (proprietary) software, no one can see the documentation. So we really never will know how complete or competent it is. Windows is a case in point.

      • (Score: 0) by Anonymous Coward on Tuesday June 06 2017, @01:36AM (1 child)

        by Anonymous Coward on Tuesday June 06 2017, @01:36AM (#521103)

        Go onto any Windows computer and press F1 at almost any time. That's their documentation. And that's what comes of following standards. Luckily must programs have yet to crap all over Window's old shortcut standards even if they did abandon everything else. Sadly many companies are turning those documents into online sites, so you can't access help when offline or when their site is being updated, but at least the shortcut key hasn't changed.

        Not all documentation is JavaDocs.

        • (Score: 0) by Anonymous Coward on Tuesday June 06 2017, @09:23AM

          by Anonymous Coward on Tuesday June 06 2017, @09:23AM (#521237)

          Go onto any Windows computer and press F1 at almost any time. That's their documentation.

          For most Microsoft software it sucks. It used to be that hitting F1 would take you to the specific paragraph that explained whatever window you are currently in. Nowadays, if you're lucky, you'll get the main index.

          If you are not lucky, you'll get something called "navigating help".

          Visual Studio is the exception. Pressing F1 on any system class, property of method 98% of the time goes straight to the MSDN page for that class/property/method. And most of them actually do explain what it does, though some unfortunately only contains the same words that were combined to give the class/property/method name.

      • (Score: 2) by driverless on Tuesday June 06 2017, @03:15AM

        by driverless (4770) on Tuesday June 06 2017, @03:15AM (#521133)

        So you can't see any of the tens of thousands of pages of MSDN, Technet, or Windows Help? Does your cult prohibit you from reading non-GPL'd docs or something? In any case though the qualifier wouldn't be "no-one can see it", it's only "members of my cult aren't allowed to look at it".