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 DannyB on Tuesday June 06 2017, @04:26PM

    by DannyB (5839) Subscriber Badge on Tuesday June 06 2017, @04:26PM (#521398) Journal

    A nice IDE can be, well, nice. In fact, I'd say that they're commonly *too* nice. They molly-coddle you and make it trivial to jump through 16 levels of function calls across a dozen source files (or even components). And this is a problem in my opinion. A developer is not penalised for writing convoluted code. And in my opinion, in the vast majority of cases, they should be. Make it a pain to follow the call chain, and people will have an actual incentive to write simpler, clearer code.

    A bad developer can (and will) write bad code using any tool, any editor, any programming language. IDEs are completely irrelevant to that complaint.

    Being able to jump through and analyze complex (and sometimes horrifical) call chains is a good thing if you're trying to understand someone else's bad code.

    Don't blame the tools. It's like blaming the tools where you should blame a bad mechanic.

    I absolutely agree bad developers who build convoluted code should be penalized, but not by the IDE or lack of one. What you have here may be less of a technical problem and more of an HR or management problem.

    I *like* having to have a mental model of the whole thing

    I like that too. Fortunately, for me, that is possible. It may not be possible for all people. Again, the IDE seems irrelevant. Or if it is relevant, I would argue that the IDE makes it easier to have a mental model of the whole thing, because the whole codebase is much easier to analyze.

    What if you had a very large project written by many people, and the whole thing was too complex to fully understand? Would you still not use a modern IDE? Or would you look for a job with a simpler code base to work on?

    You mention the template-type macros. I personally really dislike those.

    To each their own.

    And then there is my REAL bug-bear with every IDE I've ever used. They're a total !&#!% nightmare to automate!

    Maybe you're doing it wrong. I love automation. I automate anything and everything possible.

    The IDE certainly doesn't stand in the way of my build process which ultimately ends up producing a single file. (A WAR file or JAR file depending on which build target I choose.) I have a nice deploy process where the IDE is irrelevant.

    IDEs are wonderful when you're first starting out,

    I found exactly the opposite. I was intimidated by IDEs, and so I started with simpler tools. Then I used the IDE, but as just barely more than an editor. Then as I learned more and more about how to use the IDE, I came to appreciate its power.

    --
    People today are educated enough to repeat what they are taught but not to question what they are taught.
    Starting Score:    1  point
    Karma-Bonus Modifier   +1  

    Total Score:   2