I'm currently developing an API for my site, and started writing the user documentation pretty early, which is something I haven't done before. The initial release of the API is only going to have a fraction of all the methods and resources I want to support, so writing the documentation like this has really helped me get my head around the whole system, how everything should work together and what will be needed in the future.
It's funny, because I always spend a fair bit of time writing notes when programming ... but it's usually a stream of consciousness straight to a notebook via pencil - sometimes with dialog as I ask and later answer questions to myself. This really helps me find solutions to problems I'm currently working on - but is not so good at later turning into user documentation. I've tried to use a word processor, thinking that it would be easier to manipulate later into docs, but it seems that the pencil, the paper and the process all contribute to the end product.
In this case though, writing the user documentation really helped me think about the overall picture, as not only was I trying to work out the best way to implement something, but also about how my users were going to use and learn it.
Each development team at Microsoft has a dedicated documentation team. The developers typically write the API "xmldoc" level documentation, but the doc team writes the overviews, examples, etc. They also perform heavy editing and standardization of all documentation materials.
I think the docs folks I work with do a stellar job, but I think the docs would be overall better if the developers wrote them and the documentation team simply edited them. This would mean that the developers get less time to write code, but quite honestly, that is might be a good thing. There is a double digit number of windowing toolkits in active use at Microsoft...
I've been told, by more than one person, that "web apps should not need [help|documentation|training] and while I understand the sentiment I agree that the act of writing user documentation, or training materials, exposes complexity and inconsistency quite effectively.
It's funny, because I always spend a fair bit of time writing notes when programming ... but it's usually a stream of consciousness straight to a notebook via pencil - sometimes with dialog as I ask and later answer questions to myself. This really helps me find solutions to problems I'm currently working on - but is not so good at later turning into user documentation. I've tried to use a word processor, thinking that it would be easier to manipulate later into docs, but it seems that the pencil, the paper and the process all contribute to the end product.
In this case though, writing the user documentation really helped me think about the overall picture, as not only was I trying to work out the best way to implement something, but also about how my users were going to use and learn it.