Slash Boxes

SoylentNews is people

SoylentNews is powered by your submissions, so send in your scoop. Only 12 submissions in the queue.
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 termigator on Tuesday June 06 2017, @07:44PM

    by termigator (4271) on Tuesday June 06 2017, @07:44PM (#521519)

    I generally agree with your comments. Vim is still my main editor and still make use of grep when searching for things. I am way more proficient editing in Vi/Vim then any other editor.

    I have worked with IDEs like Eclipse and Netbeans. They have their uses, but when all the "magic" they do goes wrong, it can go wrong badly. This can cause one to fight the tool to get productive again, losing time getting actual project work done. I will load up an IDE to help with things like code name refactoring (a rare need) or for real-time debugging, but day-to-day, I do not use any and I make sure the projects I am lead on do not depend on any IDE.

    A problem that IDE dependency causes is developers become to dependent on it, where they can no longer be productive without it. One time, I had to set up Eclipse for a project (the project was not dependent on any IDE) for a new hire since that is what they were used to. The person did not even know how to set up Eclipse for themself. IDE heavy dev environments lead to many folks being ignorant of how things actually work. If those folks move to a different environment with different tools, they are completely lost.

    Any one who programs should at least know how to compile and run a hello-world like program in the language of choice the project uses.

    Any project should never be dependent on an IDE. Project's should allow developers to choose what IDE they want to use (or not use). In the project I am lead on now, I have two other developers using Eclipse while I do things old-school.

    Side comment: For Vim users that have to work with Eclipse, there is eclim, IIRC, that runs Eclipse in server mode, allowing you to then have Eclipse services within Vim interface.

    Starting Score:    1  point
    Karma-Bonus Modifier   +1  

    Total Score:   2