[Python-Dev] status of development documentation

[Fredrik Lundh]

Barry Warsaw wrote:

> > Sure, and some people hate using whitespace for block structure.
>
> A more proper analogy would be people who hate braces and parentheses.
> You have to type so many more < and > characters (not to mention &s
> and ;s) to make happy-joy html than you have to type \s and {s and }s to
> make nice-nice latex.

so what's *your* excuse for not using emacs? ;-)

(if you don't have sgml/html support in your editor, I recommend that you
borrow my swedish keyboard, and see if you really prefer \ { } ` etc over
< > & ...)

> > If you google c.l.python for the
> > word "documentation", you'll find recent megathreads with subjects like
> > "bitching about the documentation", "opensource documentation problems"
> > and "python documentation should be better" among the top hits.  But if
> > you check the bug and patch trackers, you don't find many contributions.
> > Something's definitely broken.
>
> I'm not convinced it's the toolchain though.  People hate writing
> documentation.  Getting people to contribute documentation is worse
> than pulling teeth.

fwiw, I seem to get more contributions to effbot.org via my really silly
HTML useredit feature than python.org gets via the patch tracker...

> If people can't install the required toolchain and they're still highly
> motivated to write Python documentation, then we already recommend
> they just write it in plain text and "someone" will mark it up.

and how motivating is it to have to wait days or weeks to be able to
see how your contribution looks after formatting?

"I had to get up in the morning at four o'clock, travel on train for eight
hours with my punch cards in a shoebox, wait twenty-nine hours for the
control data mainframe to finish, and drink a cup of sulphuric acid, ..."

</F>