[lively-kernel] [ANN] Livedoc
jens.lincke at hpi.uni-potsdam.de
Wed Nov 9 17:32:23 CET 2011
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.
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.
> (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?
> lively-kernel mailing list
> lively-kernel at hpi.uni-potsdam.de
More information about the lively-kernel