[lively-kernel] [ANN] Livedoc

[Jens Lincke]

Sure, let's try out ... :-)

Am 09.11.2011 um 17:45 schrieb Fabian Bornhofen <fbornhofen at googlemail.com>:

> Hi Jens -
> 
> being able to search and tag the doc (or any wiki page, in fact) would
> be extremely valuable.
> It's just that running another server component to search xhtml pages
> in the file system doesn't seem right to me.
> Are we or will we be able to put worlds into CouchDB?
> 
> Best,
> Fabian
> 
> On Wed, Nov 9, 2011 at 8:32 AM, Jens Lincke
> <jens.lincke at hpi.uni-potsdam.de> wrote:
>> 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
>> 
>>