On Fri, Nov 13, 2009 at 1:51 PM, Max Rabkin <max.rab...@gmail.com> wrote: > 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.) _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe