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 goodie on Monday June 05 2017, @04:46PM (1 child)
While I agree with this for an API, there is an issue with regards to JavaDoc in my opinion. Many times, there is too little documentation on the overall context of the application, just a list of hyperlinked properties and methods that say little on the "overall" way the system works. This is where your next point comes in handy (examples). In my opinion, this is where a place like MSDN does pretty well. You have the API doc, some contextual information, and at the bottom of the page, you get examples. To me, this is good documentation. But of course, it takes time to create and maintain.
Fuck yes! And keep it up to date. As a developer, there is nothing better for me than to read an example because it also helps me figure out *how* it should be done (if it's well written of course).
The thing is that writing documentation is only really working when you do it as you go, not as an afterthought once you are done. By the time you are done, your system is already doing what you need and you've moved on to something else (the thing for which you created the system to begin with!). I've seen many oss projects where I've had to go on some random person's blog to try and understand how it's supposed to be used. I don't like it, for all I know the guy is giving garbage advice and I wouldn't be able to know it.
(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 lower I set my standards the more accomplishments I have.