Chris Alexander

On Engineering

On Documentation

9th September, 2010

A few days ago on Twitter, I asked if anyone had some great resources for writing good documentation.

Unfortunately, nobody got back to me with resources, but several people expressed interest in seeing the resources if I found them.

Since then I have not been able to find any articles, blogs and so on which detail how to write great docs. However, I have completed writing a significant amount of documentation, which is now out and about in the public domain.

So I thought it would be a good idea to post about it, and see if any developer types have any suggestions for improving them.

The documentation in question is for DataSift - the API documentation.

So far the feedback has consisted of someone telling me that I write like an academic and should make my sentences shorter - so anything you have to add would be appreciated.