Regarding keeping docs up to date - I personally do NOT believe in 
external documentation, we have tried that several times and failed.

Instead I believe something like the Magic Book could work:

http://wiki.squeak.org/squeak/3004

...of which the essential idea is to use unit tests and connect them to 
"chapters" of documentation, when unit tests are updated, that typically 
signals that APIs have changed - and thus chapters are marked as 
"possibly stale".

regards, Göran