Bitching about the documentation...

[Paul Rubin]

"BartlebyScrivener" <rpdooling at gmail.com> writes:

> >>The solution is clear: the distro maintainers should require that all
> code contributions must come with good docs.
> Well, that might be asking a bit too much of the programmers, who
> perhaps don't exactly enjoy mucking about in the lowlands of English
> grammar and syntax. 

I've generally found good coders are also good writers, despite the
stereotype of the uncommunicative geek.  Some coders don't like
documenting because it's less exciting than writing code, but that
doesn't mean they're incapable of it.  After a while you learn to just
slog it out.

Docs written by non-native English speakers generally need to be
cleaned up before publication, but that's no big deal.  

> All I was saying is you should court writers and mid-level
> programmers with writing skills (not saying I'M mid-level, I'm still
> learning) to HELP with creating good documentation. When a writer
> thinks about helping they go to a page where they are greeted by a
> bug report menu or CSV notices or some such.

I just don't know to what extent a program like Python can really
benefit from docs written by non-experts in the thing being
documented.  Of course there are other types of programs, like some
desktop applications, which can be documented by non-experts.

> That's why most of your really good stuff for beginners is on
> separately created web pages, where writers simply take matters into
> their own hands. Also fine, not saying it should be different.

I don't know about this.

> Again, taking something like Bengt Richter's suggestion as just one
> example. To me the module docs are almost incomprehensible without good
> examples. Why not have a button where people could submit nice SHORT
> examples illustrating otherwise pure theoretical code and geek-speak.
> Of course, the editors would decide in a survival-of-the-fittest
> contest which example gets used, but the point is you'd get good free
> examples this way.

PHP has a system sort of like that, where each library function has
its own doc page and anyone can submit comments and examples, sort
of like a blog.  E.g.:

  http://us2.php.net/manual/en/function.metaphone.php

There's been some discussion of doing the same thing for Python, but
it hasn't been happening.

Generally, it seems to me, the parts of the docs that can be improved
much by easy additions like an example here and there, are already
usable with a little extra effort.  The docs that need improvement the
most (because they're almost unusable as-is) need extensive additions
and rewrites that really have to to be done by experts.

> In general, I'd be happy to help a programmer with writing if it meant
> I would learn programming along the way. It should be that easy. 

Maybe you'd enjoy going to a user group meeting and trying to find
people to collaborate with.  Doing that kind of thing in person is
much more fun than doing it over the net.