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 JoeMerchant on Monday June 05 2017, @01:09PM (8 children)

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

    That, and do they really not know how to write docs, or just not care?

    Coding is challenging, people dive into it with something to prove: they are masters of that universe.

    Some people will take up testing as an obsession, good testing is far from trivial and very valuable - especially to keep the coders from screwing up the existing value when they extend it.

    Documentation - lacks challenge, except perhaps in language translation, and learning more than a couple of human languages is harder than most people want to take on.

    Starting Score:    1  point
    Karma-Bonus Modifier   +1  

    Total Score:   2  
  • (Score: 2, Insightful) by Anonymous Coward on Monday June 05 2017, @01:40PM (2 children)

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

    Unfortunately, too many people believe that.

    It's not just expressing something in a human language. It's expressing it comprehensibly, efficiently and unambiguously, in a way that lends itself to translation.

    Turns out, this is basically a hard, AI-complete problem. Most devs don't have those skills. In fact, it's very hard to hire for deep technical writing positions because you need someone with technical and writing chops - and that's a very rare combination.

    The real problem is that doing a good job of this sort of writing can be a drag, and devs want to do what they find to be fun, not a drag, and there's nobody to hold their feet to the fire.

    • (Score: 2) by Grishnakh on Monday June 05 2017, @02:42PM (1 child)

      by Grishnakh (2831) on Monday June 05 2017, @02:42PM (#520760)

      It's not just Free software that suffers here though; proprietary software is no better for the most part. Quick, pull out your Windows 10 user's manual... oh wait, such a thing doesn't exist.

      The problem here, as I see it, is that technical writing is not rewarded or valued appropriately, so no one really wants to do it. The people who write software get paid well and have an interesting job (because they're creating something new), so a fair number of people flock to that profession (or do FOSS projects on the side). The people who test software generally get paid well too, so some small number of people go into that, and that's a really interesting profession too. But writing about someone else's work isn't very glamorous or fun, but worse how well does it pay? Terribly. So who's going to get a technical degree, plus a language degree(s), to be highly qualified for this job?

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

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

        So who's going to get a technical degree, plus a language degree(s), to be highly qualified for this job?

        How have so many people been indoctrinated to the point where they believe you need a degree to do anything? It's not as if knowledge only exists in colleges or universities. Lazy know-nothing employers create this situation by mindlessly requiring degrees for jobs that simply do not need them, and then they end up hiring scores of idiots who do have degrees because most schools have next to no standards anyway.

  • (Score: 2) by DannyB on Monday June 05 2017, @03:28PM (4 children)

    by DannyB (5839) Subscriber Badge on Monday June 05 2017, @03:28PM (#520788) Journal

    I wrote several items I believe in a different comment. But one worth repeating here. Change your philosophy of programming. You're not writing code for the compiler. The compiler is not your audience. Another human reader is. The exercise of programming is not merely to get successful execution on a machine. Programming is about explaining to another person how this works -- the fact that a machine can execute it is secondary.

    --
    You can not have fun on the weak days but you can on the weakened.
    • (Score: 0) by Anonymous Coward on Monday June 05 2017, @04:27PM (1 child)

      by Anonymous Coward on Monday June 05 2017, @04:27PM (#520830)

      I know I‘m being pedantic, but I disagree with the last comment that working code is secondary. Executimg code is primary. Although I totally agree with you otherwise. And I don't think this makes writing understandable code secondary either. I would argue that part of executing code is fixing/maintaining that code which includes making it easy to understand.

      • (Score: 2) by DannyB on Monday June 05 2017, @05:25PM

        by DannyB (5839) Subscriber Badge on Monday June 05 2017, @05:25PM (#520856) Journal

        You misunderstand to say working code is secondary. Working is the number one goal. If it doesn't work. Then there is no point. But the compiler processing your code is secondary to a human being able to comprehend it. The compiler doesn't count. Of course it has to work. But if it works and nobody can maintain it, then it also fails on an important level.

        --
        You can not have fun on the weak days but you can on the weakened.
    • (Score: 2) by Azuma Hazuki on Monday June 05 2017, @05:56PM (1 child)

      by Azuma Hazuki (5086) Subscriber Badge on Monday June 05 2017, @05:56PM (#520870) Journal

      Strictly speaking, the compiler *is* your audience, but so is anyone else who has to maintain it. In effect, you're trying to express yourself in a way the compiler can read that also makes sense to a human. We can trust the compiler to break the code down to its component machine-code no matter how it's written, so long as it's written correctly; for the sake of other humans, though, you should pretty-print it.

      --
      I am "that girl" your mother warned you about...