Slash Boxes

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 goodie on Monday June 05 2017, @04:46PM (1 child)

    by goodie (1877) on Monday June 05 2017, @04:46PM (#520834) Journal

    4. DO write documentation in your language's documentation system. Eg, for Java use JavaDoc. Or similar mechanism in C#. Specially formed comments on classes, methods, etc are automatically gathered and generate hyper-linked documentation that is extremely useful. Once you've used other people's good "javadoc" in your web browser, you are encouraged to write your own useful comments. But only say what is necessary to say. The identifier names should do a lot of the communicating.

    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.

    5. Write test cases in a way that serve as examples of how to use specific functions, classes, services, or whatever you are testing. These tests also become (gasp!) a form of documentation.

    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.

    Starting Score:    1  point
    Karma-Bonus Modifier   +1  

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

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

    you get examples. To me, this is good documentation.

    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.

    yes! And keep [tests] up to date.

    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. :-)

    Scissors come in consumer packaging that cannot be opened without scissors.