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, Insightful) by FakeBeldin on Monday June 05 2017, @10:54AM (5 children)

    by FakeBeldin (3360) on Monday June 05 2017, @10:54AM (#520663) Journal

    Writing good documentation is like writing a good program.
    It seems simple when you start, then it escalates, then you realise you maybe should've planned it out a bit before starting, then you go back to the drawing board, then you salvage what you can of what you have produced so far.

    Is it any surprise that someone who went to this process already for one goal is not eager to go through it fully again?
    Is it any surprise that they take the easy way out? No, sir, it isn't.

    Why does this particularly affect open source software?
    Because the challenge of writing a program or fixing a bug can be intellectually rewarding on its own, but writing the proper install guide that is easy to read isn't really. Moreover, buggy programs are also buggy for the creator, but buggy docs might be crystal clear to the creator.
    The people who like explaining things find a job or hobby to do so face-to-face. Not by sitting at home, writing for hours and hours and receiving scant positive feedback.

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

    Total Score:   3  
  • (Score: 3, Interesting) by JoeMerchant on Monday June 05 2017, @01:18PM (3 children)

    by JoeMerchant (3937) on Monday June 05 2017, @01:18PM (#520711)

    A proper install guide may be intellectually rewarding (to some) but it's socially thankless.

    In essence, documentation is "programming the users" - which is orders of magnitude more difficult than computer code. You can "get it right" for one set of people and completely wrong for the next batch, not because what you wrote is incorrect, but because the next batch interprets it differently. Expand your verbosity to cover multiple target audiences and they all lose interest: TLDR... no win.

    Україна досі не є частиною Росії. Слава Україні 🌻
    • (Score: 0) by Anonymous Coward on Monday June 05 2017, @03:10PM

      by Anonymous Coward on Monday June 05 2017, @03:10PM (#520776)

      What we need is a high level language for documentation, something that lets you write it once and then compile it for all users, instead of writing our documentation in "user level" code.

    • (Score: 2) by DannyB on Monday June 05 2017, @03:40PM (1 child)

      by DannyB (5839) Subscriber Badge on Monday June 05 2017, @03:40PM (#520794) Journal

      I tend to think that if you need much of an install guide, you're doing it wrong.

      The development team, or perhaps a separate installation team should do the heavy lifting of doing the install. How difficult is it to install Firefox? Chrome? Both of these are extremely complex pieces of software. Extremely complex.

      Try to turn installation issues into configuration issues.

      Use standard installer mechanisms for the OS, platform, language, environment, etc.

      An example of a commercial web application I developed, that, at one time, the customer could host on the customer's own equipment. Installed by their own IT people. Installation is like this:
      1. run setup.exe
      2. Next, I agree, Next, Next, (wait), Finish
      3. Server is now running. No reboot required. (Service can be seen in Windows Services control panel.)
      4. Point web browser to server. Get "Out of service" page. Use special URL to get to initial web based control panel.
      5. Use web based control panel to enter activation code, database connection information, and other very basic configuration.
      6. End result, the server is up and running, presents normal login page, ready to log in and start creating other user accounts.

      Now that sounds easy. But the development was not so easy. It was a hurdle to make the installation and set up process so easy.

      Now the above could be edited to replace "setup.exe" with "deb install file". Replace "Windows Service control panel" with "service" command. Etc.

      One further thing I learned (but have not yet done) is from a Mozilla video I saw some years back. Summary: don't build a product, build a pipeline. After the user installs it, it should be able to phone the mother ship and update itself. As easily as a TiVo does. Or Firefox. Or Chrome.

      Scissors come in consumer packaging that cannot be opened without scissors.
      • (Score: 2) by JoeMerchant on Monday June 05 2017, @07:23PM

        by JoeMerchant (3937) on Monday June 05 2017, @07:23PM (#520921)

        I agree, install guide is a bad example, software literally should install itself properly with zero intervention in all systems that even resemble a standard configuration. Maaaaybe have a few options for "advanced" users as to how invasively it integrates into handling certain file types or how many launcher shortcuts you want auto-created.

        However, the principle still applies to all forms of documentation: you're giving instructions or explanations to people, not machines - and people are much more difficult to communicate a precise set of information to. One set just needs to see: "BSD standard implementation." anything more is wasting their time, another set needs every single feature spelled out step by step with examples.

        Україна досі не є частиною Росії. Слава Україні 🌻
  • (Score: 2) by tangomargarine on Monday June 05 2017, @02:34PM

    by tangomargarine (667) on Monday June 05 2017, @02:34PM (#520754)

    Why does this particularly affect open source software?

    Because we can actually see the source? I'm not assuming this doesn't happen for closed-source projects, too.

    "Is that really true?" "I just spent the last hour telling you to think for yourself! Didn't you hear anything I said?"