In my opinion, one of the main problems of documentation is how fast it gets outdated. In the past I tried things like Specification by example and "Living documentation" but it tends to be too expensive (time and money) to be effectively used in real projects.
Right now, we're using Guru as our documentation platform. It keeps the documentation small (very important to prevent it from getting old pretty quick) and reminds authors to check their articles every now and them to see if they are up to date. I recommend to give it a try. We're pretty happy with this solution.
Thanks for sharing your experience! I've in the past tried the Literate Programming technique, but also found it very difficult to maintain.
Guru seems like a really interesting way of doing it; I'll check it out. My first impression is that it seems like it focuses on the experience of writing and using the documentation, which I like.
We're a place where coders share, stay up-to-date and grow their careers.
We strive for transparency and don't collect excess data.