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) by tangomargarine on Tuesday June 06 2017, @02:55PM

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

    I'm sick of typing a loop only to have the script fail because my editor decided it needed to throw in some extra loop closures for me. Who are these systems designed for? What coder is such an atrocious typist that typing a damn closing parenthesis is something that needs to be automated? All that does for me is break my concentration and waste effort...I've gotta type it, then I've gotta notice something went weird and reanalyze the line I just typed to get everything matched up again. I cannot conceive of any reason why anyone could possibly believe that was a good feature to implement, let alone making it default behavior...

    It's kind of weird -- auto-parentheses seem natural to me in Eclipse, but when I enabled a mode in emacs to do it, it drove me nuts for a couple days until I turned it off again. Maybe it's a C++ vs Java thing, or a workflow difference...

    It's too bad code tags in emacs (the equivalent of F3 in Eclipse) look like such a mess. This being a Linux tool, of course there are 3 or 4 different ways to do it.

    It's like at work we use this software called Informatica, it's kind of a drag-and-drop IDE for large database ETL operations. And it's the worst thing I've ever worked with, because if their tools don't have a feature you need, you're just screwed. It outputs code as XML files, and if you export the exact same code twice you'll end up with two different files. It'll output stuff in different orders, give components different names, add or remove extra null attributes on tags...if you want to compare changes between two versions the only option is load them both in the IDE and manually compare one section at a time. Their IDE doesn't have any kind of diff feature and the exported XML is too variable to use standard tools like diff. And even the features it does have don't work -- you'll open a transformation, copy some text from it, close it and open the find box and paste that same text right in there...and it won't find it. If you have specific text to find you can kinda do that in notepad on the XML, then you've gotta trace back the hierarchy, which will give you something that you can put into the Informatica find function that it *might* be able to work with, then you can go back there to try to look at the actual code...it's a goddamn mess. Not to mention that most configuration values can be changed or overridden multiple places, without any indication of which one is actually going to be used...but that's another topic probably.

    Wow. Sorry :-/

    I'm pissed that I can't use diff, but I'm probably the only person here who would even bother to try. Everyone else just goes "Can't find what changed, let's schedule a meeting."

    Kind of like how the search in Windows is so dysfunctional sometimes I can search for the name of a file in the same directory and it won't find it. So rather than even try, I just fire up Cygwin these days.

    --
    "Is that really true?" "I just spent the last hour telling you to think for yourself! Didn't you hear anything I said?"
    Starting Score:    1  point
    Karma-Bonus Modifier   +1  

    Total Score:   2