without an e

Your Documentation Sucks [09/14/2008 20:38:55]

Guys, I'm really trying.

Yeah, I know you've already solved my problem.

Yeah, I know it's more work to write my own code than to use yours.

But the thing is... Your documentation sucks.

It may be more work to write my own code, but it's far less frustrating than reading your docs.

Let's name some names here.

Hey Glyph Lefkowitz! The twisted documentation sucks!

Hey Ian Bicking! The paste documentation sucks!

Hey Richard Jones! The roundup documentation sucks!

Hey Phil Eby! I honestly don't know whether The EasyInstall documentation sucks or not because I've usually given up by the time the page loads. is pretty darn good. But your page load time sucks!

Hey Armin Rigo! The PyPy documentation sucks!

Hey Kay Schluehr! The EasyExtend documentation sucks!

You guys are responsible for some of the coolest, smartest python projects out there. I'm sure they're all worth the learning curve... If only I had time to decipher your documentation.

I'm not unreasonable. I ditched the home-grown template system that I used for years in favor of genshi. Genshi solved my problems, and it's got fantastic documentation.

In fact, other than PyPy and EasyExtend, I use all the above tools in my company - some of it on a daily basis.

But the simplest, one-line tasks take me hours and hours to accomplish (or just don't get done) because I can't understand your documentation.

I would be happy to sponsor a rewrite. You're wasting my time and costing me money so a rewrite would almost certainly have a positive ROI. Heck, I'd be happy to rewrite the docs myself.

The only problem is... I don't know enough about your apps to explain it to anyone, and I don't know how to obtain that knowledge.

Can you guess why?

It's because your documentation sucks. :/

Use the source Luke.
by zep [09/15/2008 06:59:19]
You know what helps? Filing actual bugs on problems you found with documentation. You know what does not help? Ranting.
by Moshe Zadka [09/15/2008 07:39:05]
Moshe: whenever anyone posts a blog entry about asynchronous programming in python, a bunch of twisted guys show up and shout "No, you idiot! You should be contributing to Twisted!"... Your finger tutorial is actually quite good, but the reference documentation is very spotty. Very simple example: try figuring out how to set up twisted as a WSGI container. It's a nightmare.
by Michal [09/15/2008 08:06:26]
Guess I didn't really finish that thought. My point was that if you want more people to contribute, you should be proactive and improve the documentation. If you can't take the time to explain things clearly, don't be surprised when people choose to write their own tools rather than reverse-engineer your code.
by Michal [09/15/2008 08:12:03]
Michal, after reading your post I feel vindicated. :)
by George [09/15/2008 09:39:50]
For the record :) - I had an asynchronous programming problem that had been driving me crazy about six months ago, and had the gall to ask for help with it on #twisted, and was stunned when I got *really good* help from a couple of twisted celebrities when they would have been well within their rights to boot me for OT :). After that, I was unable to learn twisted from their docs and only started to break through when I moved to the O'Reilly book. But I took notes as I went through both their docs and the book, and when I went on #twisted to discuss these people were super-eager to discuss it and talk about possible improving. I've dropped the ball since then due to focus changes and hope that I'll get back to it at some point. Having said all that, I fall over myself to agree with the spirit of your post. There is a cultural problem alive in the python world and other communities that thinks that if something can be made to work then it's finished. I'm not sure what can be done about it other than for people who are good at technical writing to get out there, pick some frameworks with maintainers who genuinely want help, and put some effort in. With all the diversity of frameworks we get this day and the low barrier of entry, it's inevitable that the future will have lots of poor efforts. It's not worth trying to save the poor groups from themselves. I think you need to have good criteria for distinguishing in your own mind between framework communities that get it and those that don't and then focus on using or even improving the good ones. It's always useful to know about good frameworks like genshi.
by cratuki [09/15/2008 14:09:13]
As the author of many Perl libraries, I feel both the pain on both sides. Writing good docs, especially for a big, multi-faceted tool, is just very, very hard. To compound things, the core programmers are often in the worst position to write non-API docs (tutorials, recipes, etc) because they can't see things from the viewpoint of a noob. If you use these projects and are willing to sponsor, maybe you could coordinate a documentation effort made up of people _not_ in the core teams. Users who've had to struggle to understand a badly documented system are often in a great position to write exactly the docs they would have needed to struggle less ;)
by Dave Rolsky [09/15/2008 16:22:53]
hey michal, your blog sucks!
by billy [09/15/2008 16:58:57]
Up until recently, you could have also counted Beaker in that list. One of the major problems seems to be that project authors write documentation for themselves, not for their users. While I agree, to some extent, w/ the first comment (file tickets against bad or good but incorrect/out-of-date docs), if you get a response at all it'll often be to the effect of, "I'm too busy doing cooler things." Lame. I'm certainly not making excuses for awesome projects with crap docs, but it's rare to find a coder interested in coding /and/ writing docs much less good at both.
by xunil [09/17/2008 16:03:59]
*One of the major problems seems to be that project authors write documentation for themselves, not for their users.* This might be provisional though. Documentation can rapidly evolve as the project matures. The developers need confidence that they don't have to re-document too much. Once you are doing major refactorings, changes of perspectives or the introduction of new concepts the docs may need a major rework as well. Speaking for EasyExtend this has been the case more than one time. BTW looking at the list of projects being mentioned in the rant I'd likely exclude that the authors are big-ego infantile coders with the attitude "coding is cool but writing documentation is not".
by Kay Schluehr [09/18/2008 02:40:58]
Hey, Micah, In general, I agree with your post. I am new to python and spending most of my time in actual books at the moment in order to pick up the language. I have looked through some of the documentation for various Python projects and have been stunned with how poor it is in general. I guess I am used to looking through the Perl CPAN (and I am not a Perl guy either) and generally finding them to be pretty good.
by Jim [09/18/2008 16:31:22]
I totally agree, but then again, I'm a technical writer :-) @zep: Yes, if you're a programmer trying to understand a library, you can "Use the source, Luke". But reading and understanding code often takes a lot more effort than reading and understanding English. And every person who needs to understand the code has to pay that same high cost, from scratch. Whereas, if one person who understands the code writes some documentation, then everybody after that benefits. Some things that project maintainers can do to lead to good docs for their projects: 1) Start the ball rolling by writing what you can. It may not be written from a user perspective, but it gives users something to bootstrap from. 2) For new APIs, don't consider it done without docstrings. 3) Make it easy for community members to contribute. Some ways to do this: a) Create tickets like "Document module xyz", so that people can submit doc "patches". b) Use tools like Sphinx and pydocweb (https://code.launchpad.net/~pauli-virtanen/scipy/pydocweb) so that people can easily contribute documentation for whatever small piece they understand. Avoid monolithic "guides". c) If someone submits a code patch, ask them to write docstrings for the relevant code---not as a penalty, but because they had to understand that function/class/etc. to make the fix. Capture that knowledge, so others don't have to work so hard in future. d) Once you have docstrings, review them whenever the code changes, to ensure they sync.
by Janet [09/25/2008 18:24:04]
So let's be specific. I'm a little familiar with Roundup and would like to contribute by improving the documentation. What in particular did you want to do that could be better explained in the documentation?
by Andy Todd [09/28/2008 03:57:59]
XGMnzc <a href="http://jameaybcrbnj.com/">jameaybcrbnj</a>, [url=http://cofaaxvciuwb.com/]cofaaxvciuwb[/url], [link=http://ydirumsebvue.com/]ydirumsebvue[/link], http://vtjuiecdeqgf.com/
by ygajkgc [10/05/2008 22:22:54]
XGMnzc <a href="http://jameaybcrbnj.com/">jameaybcrbnj</a>, [url=http://cofaaxvciuwb.com/]cofaaxvciuwb[/url], [link=http://ydirumsebvue.com/]ydirumsebvue[/link], http://vtjuiecdeqgf.com/
by ygajkgc [10/05/2008 22:22:55]
XGMnzc <a href="http://jameaybcrbnj.com/">jameaybcrbnj</a>, [url=http://cofaaxvciuwb.com/]cofaaxvciuwb[/url], [link=http://ydirumsebvue.com/]ydirumsebvue[/link], http://vtjuiecdeqgf.com/
by ygajkgc [10/05/2008 22:22:57]
Post a comment:
name: (shows up on site)
link: (shows up on site)
mail: (for michal only)
no html allowed yet. sorry: