Quote Originally Posted by bridgman View Post
IMO the solution is to find the right level of detail. I think everyone agrees that documenting where to find the code and how to build/install it is worth doing, so the question is whether documenting one or two more levels of detail would help and where we reach the point of diminishing returns. I suspect we reach that point quite early, ie that the optimal point would be maybe 5-10 pages *total* of well-written design docco divided across the major component projects (eg a page or two for stack-level plus a page or two for each major component) and kept ruthlessly up to date.

That would be enough to let potential developers get a lot further into the code quickly, and hopefully enough that they can start tinkering and asking good questions (where "good" in this case means "other developers feel that answering the questions is a good use of their time").
That sounds good to me. Is this something on your mind "only" or has that been discussed already with the right people willing to do this work?

What's also missing, IMHO, is a glossary. Or does it exist already and I didn't find it? It may sound trivial but having things like "stride"* explained in a few words,
might turn out valuable for beginners and non-native speakers of english. I guess this is a rather static thing and mostly new entries need to be added.

[*] Maybe not the perfect example but you might get the idea.