[lively-kernel] [ANN] Livedoc

[Fabian Bornhofen]

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