Documentation - the oft neglected step-child of a project

I've recently started contributing to the documentation for the Orchard CMS project (GitHub: https://github.com/OrchardCMS/OrchardDoc), my reasons for this are many:

1. I've been using Orchard as the CMS for my website for a couple of years now, not really digging into it/how it works, and wanted to "give something back"
2. Having created a new module for Orchard (and used the documentation for that), I've seen where the docs have got out of step with reality - applying my freshly gained knowledge to bringing them up-to-date is a no-brainer
3. I want to, at some point soon, contribute improvements to the code for Orchard itself (as I've noticed a couple of "peculiarities" in places); working on the documentation is a good way to get a handle on how GitHub works (as I've not really used it in anger before, we're an SVN house here!) and also on how to contribute to OrchardCMS projects in a way that works for those that "run" it
4. Documentation is an oft neglected step-child, I want to give it a bit of love and bring it up to date!

In my "day" job, I've spent the past I don't know how many weeks documenting various parts of the system, so I've really got a "documentation" head on at the moment and it's made me realise just how many assumptions and "well that's obvious" places there are within systems when you're looking from the inside out; making sure that documentation covers both the "obvious" and, more importantly, the "obvious to me" points is something that I've come to appreciate that little bit more recently. This is especially true when I send a document out for review and get feedback with suggestions for areas to add / cover in more detail that seem obvious, with hindsight.

I also recently ended up reading Unit tests are to testing… by Bertrand Le Roy (one of the guys behind Orchard) where he talks about testing but then segues into a bit of commentary about documentation:

In a similar move, it seems like the documentation writer specialty has all but disappeared. Take this random MSDN topic: http://msdn.microsoft.com/en-us/library/dd493110(v=vs.118).aspx. There is zero information in there. You don’t know why this is useful, there is no code sample, no context, just a lazy and uninformative description of what the code technically does, but nothing about what it functionally achieves.

Compare this with this topic from 2000: http://msdn.microsoft.com/en-us/library/ms972337.aspx. That is very helpful, and a tech writer has clearly spent a lot of time writing it. Nowadays, it seems like the documentation is just what a bot could extract from what little XML doc comments the developers put in their code, and a few top-level articles. I suppose in a world of mediocrity where most projects don’t even have that, it can look passable. While an open source project can get away with it, relying as it is on the good will of its contributors, a major software company that really wants adoption has got to do better.

There's a lot of truth to that there (written 3 years ago, and I think things have only declined!), documentation is an art form that needs life breathing into it. Terse automatically generated documentation is often little better than having nothing at all, but long-form documentation that explains the How/What/Why of something is harder to write, and even harder to get right. Hopefully I'll manage it!