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
