Re: Linux docs (was:Re: [tlug] Re: IPv6)

["Stephen J. Turnbull" <stephen@example.com>]

Darren Cook writes:

 > >  > How hard is it to get involved in documentation projects?
 > 
 > Stephen wrote:
 > > It's a bitch.  You really need to understand the project's code, and
 > > know what the developers are trying to accomplish, to do it well.
 > > ...

I see it wasn't clear what I'm referring to.  It's not hard to join a
doc project and write a one-off tutorial, but writing good docs for
the general user is hard.  If you want to get "really involved" to the
point where you can be proud of what you're doing, generally you do
have to know a lot.

 > > You can always report bugs against documentation, but those often get
 > > ignored because the developers think they're gonna change the behavior
 > > anyway.
 > 
 > I've never had this impression. Must be an emacs thing ;-).

Actually, both Emacs and XEmacs are better than average in this
respect.  I don't like the style of GNU Emacs docs, but rms and the
crowd around him at Emacs definitely insist on good documentation.  We
don't make as much official noise about it, but we can mostly take
advantage of good GNU docs, and add some of our own.

 > I think most programmers of most open source projects would bend down
 > and kiss your feet if you offered to write documentation, especially if
 > it is tutorial/how-to documentation, which the main developers are
 > generally incapable of.

Could be; I guess I've just been at it too long to really appreciate
how much help even a bad tutorial can provide.  My experience on the
other side is often of the "oh Gawd, where did you hear *that*?" when
getting a bug report that something doesn't work as expected.

 > Knowing the internals is very much optional.

Did I write "internals"?  If so, I take it back.  But there are a
plethora of special-purpose options and techniques available in the UI
in most software, such as the alias devices that Scott mentioned.
These tend to get overlooked by both the developers' documents and by
tutorials.