On Fri, Nov 13, 2009 at 1:51 PM, Max Rabkin
I have heard many complaints about the average quality on documentation. Therefore, I'd like to encourage you all to read Jacob Kaplan-Moss's series on writing great documentation: http://jacobian.org/writing/great-documentation/. The articles are themselves well-written and contain excellent advice (though I disagree somewhat with the comments on automatically-generated documentation: I find many libraries are excellently haddocumented). Jacob Kaplan-Moss is a developer on the Django project, which is well known for the quality of its documentation.
Some of the advice is decent, but some (e.g., "edit on paper", "avoid editing and writing simultaneously") I could never bring myself to do; the ability to continuously revise mid-stream is what keeps me *sane*, and the only reason I can write at all. (It probably helps — or hurts? — that I'm positively neurotic when it comes to grammar and usage.)