[ANN] Livedoc

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

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

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