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 turgid on Monday June 05 2017, @02:33PM (3 children)
None of my programs have man pages. That would be another boring and stupid markup language to learn and more stuff to keep up to date :-) And if you write a man page some poor soul might get the mistaken impression that your code actually works and can be used...
I refuse to engage in a battle of wits with an unarmed opponent [wikipedia.org].
(Score: 0) by Anonymous Coward on Monday June 05 2017, @07:15PM (1 child)
FWIW, if you write documentation in almost any form, your build scripts can use pandoc to change it to man pages.
(Score: 2) by kaszz on Monday June 05 2017, @11:43PM
That is time spent learning the idiosyncrasy of those build scripts and pandoc that could been spent on writing code.
(Score: 2) by kaszz on Monday June 05 2017, @11:39PM
Make a simple text file. It solves a lot for very little effort.