SoylentNews is people
SoylentNews
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.
-- submitted from IRC
(Score: 2) by DannyB on Monday June 05 2017, @03:28PM (4 children)
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.
Stop asking "How stupid can you be?" Some people apparently take it as a challenge.
(Score: 0) by Anonymous Coward on Monday June 05 2017, @04:27PM (1 child)
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
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.
Stop asking "How stupid can you be?" Some people apparently take it as a challenge.
(Score: 2) by Azuma Hazuki on Monday June 05 2017, @05:56PM (1 child)
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...
(Score: 2) by JoeMerchant on Monday June 05 2017, @07:26PM
Documentation isn't just for programmers, either. A vast swath of open source code completely lacks user facing documentation.
🌻🌻🌻 [google.com]