Bitching about the documentation...

BartlebyScrivener rpdooling at gmail.com
Mon Dec 5 19:10:05 CET 2005


>> It's tough to put yourself in the shoes of a
novice, so it's tough to write documentation that would be helpful for
new
users.  It's extremely helpful if new users submit documentation
patches as
they figure things out.  It's generally unnecessary to write large
tomes.
Often all that's needed is a few sentences or an example or two. <<

Yes, well, regardless of your beef with the person who complained about
documentation, I respectfully submit that it is not so easy to help out
with documentation. I'm a professional writer and author with a keen
interest in open source, but the moment you look to contribute or try
to help with the documentation you are asked to learn LaTex or DocBook,
which, I'm sorry, I am not going to do.  Authors and writers are
usually drawn to open source software by their love of plain text.
Even veteran Linux users have a lot of trouble with LaTex, so the
writers, who perhaps would be willing to help with writing in exchange
for help with programming, are unable to do so without learning yet
another arcane and foreign mark-up language, which frankly won't be
useful in any other writing endeavor. How about a compromise, like
having documents submitted in html or some other system that is more
cross platform than LaTex?

bs




More information about the Python-list mailing list