If we're drowing in documentation (and I always prefer to err on the side of too much data rather than too little), then it's in low quality, incomprehensible documentation, not the good stuff. One of the weaknesses of open source is the difficulty outsiders have understanding that freely available code (programmers would much rather program than document their work, which is why making one's code self-documenting is always a plus). Experimentation is good (if one has time), but easy to learn is better.
--------------------------| John L. Ries | Salford Systems | Phone: (619)543-8880 x107 | or (435)867-8885 | --------------------------| On Thursday 2016-11-17 07:58, Richard Owlett wrote: >Date: Thu, 17 Nov 2016 07:58:55 >From: Richard Owlett <rowl...@cloud85.net> >To: debian-user <debian-user@lists.debian.org> >Subject: Re: Why? -- "A Modest Proposal" >Resent-Date: Thu, 17 Nov 2016 14:59:21 +0000 >Resent-From: <debian-user@lists.debian.org> > > On 11/16/2016 9:37 AM, to...@tuxteam.de wrote: >> >> >> On Wed, Nov 16, 2016 at 08:13:49AM -0600, Richard Owlett wrote: >>> There exist SOC <Summer of Code> projects to encourage/mentor >>> fledgling programmers. >>> Considering the state of documentation, esp man pages, why no SOD >>> <Summer of Documentation> projects for potential tech writers. >>> >>> In many areas, nerds are considered illiterate. I can see SOD >>> projects as a vehicle to encourage technically oriented teens to >>> hone their composition skills. Attempting to edit existing man pages >>> might be a good starting point. It would obviously require mentors >>> with an atypical mixture of skill sets. >>> >>> P.S. Apologies to J. Swift ;) >> >> There are quite a few initiatives underway which are changing the >> world -- too many to mention, from low to high. >> ... > > I've used the Arch wiki many times. I'm not familiar with the others. I think > I have a long term reading assignment. > >> >> We're drowning in documentation. Even more: if we only kept the >> 10% "good" doc we'd be still drowning in it. Could it be better? >> You bet! But the main problem is... books is not all. >> ... > > My intention was to focus on two aspects of man pages in general: > 1. they can use improvement > 2. sketch a means of attracting young people to tech writing > >> >> Same here: su's man page is imo excellent. It could be made >> better (you're in a good position to make proposals, since >> it seems that you just mounted an obstacle and might have a >> fresh memory of how this obstacle felt to you). But sometimes >> it just takes another person with a fresh perspective to >> get the right nudge at the right time. Then, all of a sudden, >> the darn thing becomes readable :) > > My only problem with the su man page was not having read it. > I thought I understood su, sudo, etc. ERROR ;/ > >> >> (Note that I'm not arguing against the point you made above. >> If we could attract more resources into making people better >> documenters, I'm all for it -- it is at the heart of free >> software after all). >> >> regards >> >> [1] http://man7.org/ >> [2] https://blogs.s-osg.org/author/mchehab/ >> [3] https://lwn.net >> [4] https://kernelnewbies.org/ >> [5] https://wiki.archlinux.org/index.php/ >> >> - -- t > > >
