One of my source of shame and bad feelings is the current state of SimGrid overall documentation. Even if you define "documentation" veeery widely, our documentation is a real pity. We never had a really strong documentation, but things are really getting worse.
On the web site, the FAQ was not really updated since ages. Autoconf stuff is still to be found here and there, while we switched to cmake in March 2010. And that's only an example, I really have to rework that FAQ. The most recent version listed on the History page is the 3.2, while 3.3 was released in April 2009. And that's only what I'm aware of. I feel quite depressing to crawl our site nowadays given all this work remaining.
In the source tree, there is a whole bunch of examples, but they are not easy to navigate, and some are even plainly misleading. For example, some (most?) of the MSG examples still exchange tasks using the put/get interface, which was deprecated in flavor of send/receive since at least version 3.4, released in April 2010. The reference documentation extracted through doxygen is in a good shape, but that's a bit limited for newcomers.
On the scientific publication front, we have quite a bunch of papers about differing parts of the framework, but the central publication, which should constitute an entry point and be the reference publication is a 6 pages paper from 2008.
The best source of information may be the tutorial I gave at HPCS in june 2010. That's a 4 hours tutorial, but it's still short given the corpus of knowledge that we accumulated in this project over the time.
I'll work on this next year, during my teaching exemption. But in the meanwhile, I think that our users would be perfectly entitled to insult us and yield Write The Fucking Manual!