[lively-kernel] [ANN] Livedoc

[Jens Lincke]

Hi, Fabian -

great! I like the new pages. Thanks for doing this work.
What about tagging and searching of these worlds (or general lively worlds) in that case. 
We had a server side component for that, but maybe it is a good idea to build a search tool that can search these pages 
well and we can generate these things....

Cross referencing them in source code is also a very good idea.

Best,
Jens


On 09.11.2011, at 03:55, Fabian Bornhofen wrote:

> 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
> lively-kernel at hpi.uni-potsdam.de
> http://lists.hpi.uni-potsdam.de/listinfo/lively-kernel