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 > [email protected] > http://lists.hpi.uni-potsdam.de/listinfo/lively-kernel _______________________________________________ lively-kernel mailing list [email protected] http://lists.hpi.uni-potsdam.de/listinfo/lively-kernel
