Re: Why? -- "A Modest Proposal"
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
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.
In the realm of man pages, there's Michael Kerrisk [1], working
at it since time immemorial. In the realm of Linux kernel
documentation, there's a new initiative, led by Mauricio Carvalho
Chehab [2] and supported by LWN's inimitable Jonathan Corbet [3].
For those trying to climb the steep kernel ladder there's
kernelnewbies.com [4]. For a very broad brush on Linux user space
there's the excellent Arch wiki [5]. Debian itself has recognized
that there are more roles than "just" maintainer, so there's room
for documenters now. There's the venerable Linux Documentation
Project, from which a sizeable part of your /usr/share/doc derives
(on my box this is 2.3G of compressed stuff: just sayin'). I didn't
mention Debian's huge resources, since I assume most are well-known
here. There's Wikipedia, which in the technical realm is, overall,
pretty good.
And the other 53479 I didn't mention, because I don't even know
about most of them.
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.
Take Richard Feynman's "Lectures on Physics" or Knuth's "The
Art of Computer Programming". Reading the one won't make a
theoretical physicist of you (unless you're exceptional: yes,
such folks exist!), reading the other won't make you a computer
scientist. Books are one building block, there are others, as
mentoring and experience.
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 :)
(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
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.12 (GNU/Linux)
iEYEARECAAYFAlgsfSYACgkQBcgs9XrR2kYHeQCfVCFO2Tv2BoZKOSuQUDQJuQ8o
WscAn0EtNE9xuoxsVEbDTfzHKqkw/tw6
=gSIz
-----END PGP SIGNATURE-----
Reply to: