Hi - lately, Lauritz and I have put quite a lot of work in stabilizing Lively 2. Obviously, we were not the only ones to think that Lively could use more documentation, but we were not sure how to do it. We now decided to try a live approach: Grow and maintain documentation on the fly and in Lively itself. For us this means that whenever we fix a bug (or add a feature) that requires us to do a significant amount of research, we want to explain both general concepts and implementation details of it in a Lively page.
In the first step, we added new folder hierarchy that should (eventually) reflect Lively's subsystems. http://lively-kernel.org/repository/webwerkstatt/documentation/livedoc/ (we start with three pages in there, please don't expect too much :) ) Consequences will be: - Developers can learn about concepts and design decisions without searching for code snippets and interpreting them. - Livedoc pages can contain not only descriptions of problems of solutions but also live examples. - Documentation will be far from comprehensive at the beginning (now). - It has to be kept up to date. - We can neither tag Livedoc pages nor easily cross-reference them unless we put them into a database (let's do that!) - The ideal result would be a handbook of Lively's design and implementation - We still need to put some thinking into entry-level documentation and tutorials for our tools. What do you think? Best, Fabian _______________________________________________ lively-kernel mailing list [email protected] http://lists.hpi.uni-potsdam.de/listinfo/lively-kernel
