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: 3, Interesting) by hendrikboom on Monday June 05 2017, @08:12PM

    by hendrikboom (1125) Subscriber Badge on Monday June 05 2017, @08:12PM (#520951) Homepage Journal

    I've started predocumenting. I start to explain what I'm trying to do and how I'm trying to do it in English. It's often quite vague, but it shows the approach I'm taking, and after a while, also shows the approaches I'm not taking. It's only after I do this that I start writing code. Sometimes the predocumentation ends up as comments in the code, sometimes not.

    And I always have a lot of TODO comments -- places where I'm not quite sure I've done something the best way, or even an adequate way. Sometimes I know it's not the right way, but I know the code will enable me to write and test other parts of the code. That gets a TODO. Sometimes i know what I wrote won't scale up. That gets a TODO. The TODOs look very informal, and that is the right level of precision.

    Of course the code doesn't match the predocumentation. For one thing, the predocumentation contains the approaches I could have used as well as the one I finally ended up using. And a battle plan doesn't survive contact with the enemy. But I often find that what I planned to do doesn't work long before I end up debugging. That saves me a lot of work.

    At all times, the code and the associated documents present what actually there and what should be there, incompletely and approximately. The writing doesn't look definitive. I find it useful a year later when I'm looking at the code again. It tells me what on earth I was thinking when I wrote it.

    Anytime the code confuses me when I come back to it, I figure out what's going on and document it. Or document what it should have been and make the necessary changes.

    Starting Score:    1  point
    Moderation   +1  
       Interesting=1, Total=1
    Extra 'Interesting' Modifier   0  
    Karma-Bonus Modifier   +1  

    Total Score:   3