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, @05:23PM
I have sometimes written simple examples, and fragments, in the JavaDoc documentation. Thinking of the poor sop who may one day maintain this code. And it will be around a long time. I will probably expire before it does. Code I wrote in the early 80's wasn't phased out until the early 2000's -- also forcing us to deal with Y2K. Code I wrote in a newer language in the 90's is still being used today, but being phased out by encouraging upgrades to what I work on today.
If they are not up to date enough, then they fail. You have to fix them, and in the process you are fixing your examples of how to use the system being tested. You can also write JavaDoc comments in the tests. :-)
The Centauri traded Earth jump gate technology in exchange for our superior hair mousse formulas.