[Haskell-cafe] Writing great documentation

[Tom Tobin]

On Fri, Nov 13, 2009 at 1:51 PM, Max Rabkin <max.rabkin at 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.)