[lively-kernel] [ANN] Livedoc

[Fabian Bornhofen]

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
>
>