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 JoeMerchant on Monday June 05 2017, @07:23PM
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.
🌻🌻🌻 [google.com]