You are viewing a plain text version of this content. The canonical link for it is here.
Posted to user@lenya.apache.org by Giampaolo/Trapo <ne...@trapo.it> on 2004/05/07 09:36:12 UTC
Wiki or documentation?
Hi list,
maybe this issue is a bit delicate. We all agree that documentation of
the project is important as the projects itself (ie code) and that to
get Lenya popular a good documentation is strategic. However i see that
in ml (and in irc channel as well) the wiki is referred more times than
documentation. I try to wonder why:
Wiki has FAQ,
Wiki points to HowTos,
Newbie feels that Wiki is more up to date than documentation,
Simple update mechanism for committer.
Questions (maybe silly)
how to get information on wiki consistent with documentation for this
points of view:
* definition and terms (not only the term itself but also how is displayed)
* information itself
* can documentation refer to specific pages of wiki and viceversa?
* can documentation incorporated someway into wiki?
* which should updated first?
Giampaolo/Trapo
---------------------------------------------------------------------
To unsubscribe, e-mail: lenya-user-unsubscribe@cocoon.apache.org
For additional commands, e-mail: lenya-user-help@cocoon.apache.org
Re: Wiki or documentation?
Posted by Christian Egli <ch...@wyona.net>.
Giampaolo/Trapo <ne...@trapo.it> writes:
> Hi list,
Hi Trapo
> maybe this issue is a bit delicate. We all agree that documentation of
> the project is important as the projects itself (ie code) and that to
> get Lenya popular a good documentation is strategic.
Thanks for bringing this important issue up.
> However i see that in ml (and in irc channel as well) the wiki is
> referred more times than documentation. I try to wonder why:
> Wiki has FAQ,
> Wiki points to HowTos,
> Newbie feels that Wiki is more up to date than documentation,
Which is probably true.
> how to get information on wiki consistent with documentation for
> this points of view:
> * definition and terms (not only the term itself but also how is
> displayed)
This should probably done in the documentation proper and refered to
from the wiki. Afaik there are some pages (in the documentation) which
define terminology (such as document-id, etc.).
> * information itself
Are you asking how to get the info on the wiki consistent with the
info in the documentation? For that I suggest that we draft the
documentation in the wiki and as soon as we identify this page as
interesting enough for the documentation proper we consolidate it and
migrate it to the documentation proper (see also below).
> * can documentation refer to specific pages of wiki and viceversa?
I see the documentation as a more static thing than the wiki. I would
therefore not have references from the documentation to the
wiki. Possibly the other way around. If you want to refer to some page
in the wiki from the documentation it's probably a sign that this
document needs to go into the documentation
> * can documentation incorporated someway into wiki?
I guess you can link to it from the wiki.
> * which should updated first?
I would say do whichever you like more. Documentation is always
useful, be it in the wiki or in the proper documentation. IMHO
documentation can first be drafted in the wiki and then consolidated
and migrated into the proper documentation. Since our documentation is
based on forrest I think it should also be able to handle wiki pages,
so the migration should be quite painless.
>
> Giampaolo/Trapo
--
Christian Egli christian.egli@wyona.net +41 1 272 9161
Wyona AG, Hardstrasse 219, CH-8005 Zurich
Open Source CMS http://www.wyona.org http://www.wyona.com
---------------------------------------------------------------------
To unsubscribe, e-mail: lenya-user-unsubscribe@cocoon.apache.org
For additional commands, e-mail: lenya-user-help@cocoon.apache.org
Re: Wiki or documentation?
Posted by Brian Maddy <br...@brianmaddy.com>.
Sorry, I wasn't very clear. By 'documentation editors' I meant the
people who have access to edit the documentation on the web page.
Brian
Rolf Kulemann wrote:
> On Fri, 2004-05-07 at 16:40, Brian Maddy wrote:
>
>>I don't get it, why wouldn't it just be possible to create a wiki page
>>called documentationUpdateRequests? Wiki users could put their update
>>requests in there, along with a brief description as to why they thing
>>the change should be done. Then the documentation editors could update
>>the documentation whenever they get some time to do so.
>
>
> Which editors?
>
> The thing is, I would appreciate a way that we can easily integrate user
> written wiki docs into documentation.
>
---------------------------------------------------------------------
To unsubscribe, e-mail: lenya-user-unsubscribe@cocoon.apache.org
For additional commands, e-mail: lenya-user-help@cocoon.apache.org
Re: Wiki or documentation?
Posted by Rolf Kulemann <ro...@apache.org>.
On Fri, 2004-05-07 at 16:40, Brian Maddy wrote:
> I don't get it, why wouldn't it just be possible to create a wiki page
> called documentationUpdateRequests? Wiki users could put their update
> requests in there, along with a brief description as to why they thing
> the change should be done. Then the documentation editors could update
> the documentation whenever they get some time to do so.
Which editors?
The thing is, I would appreciate a way that we can easily integrate user
written wiki docs into documentation.
--
Regards,
Rolf Kulemann
---------------------------------------------------------------------
To unsubscribe, e-mail: lenya-user-unsubscribe@cocoon.apache.org
For additional commands, e-mail: lenya-user-help@cocoon.apache.org
Re: Wiki or documentation?
Posted by Brian Maddy <br...@brianmaddy.com>.
I don't get it, why wouldn't it just be possible to create a wiki page
called documentationUpdateRequests? Wiki users could put their update
requests in there, along with a brief description as to why they thing
the change should be done. Then the documentation editors could update
the documentation whenever they get some time to do so.
Brian
Rolf Kulemann wrote:
> On Fri, 2004-05-07 at 12:18, Thorsten Scherler wrote:
>
>>Rolf Kulemann wrote:
>>
>>
>>>Nice idea but a quite big approach which is imho worth to follow. Maybe
>>>all this goes into direction of doco?
>>>See http://wiki.cocoondev.org/Wiki.jsp?page=Doco .
>>>
>>>Maybe a good topic for a sprint.
>>>
>>>
>>>
>>
>>Nice, Rolf!
>>Jupp, I guess that doco would be the way to go!
>>
>>Sprint -> I would love to attend thus an event! Is it possible to be
>>part of a sprint but not being e.g. in Zuerich (online)? I wouldn't mind
>>hacking a weekend with you guys (I would love to)!
>
>
> FYI:
>
> I have more or less "green lights" from Uni here in Hannover to do a
> sprint there....but since u are in spain...same problem for u to come to
> Zurich. However, most Lenya people come from Zurich, so it makes sense
> to do sprints there.
>
> If it is an option to do Lenya sprints in germany, let me know.
>
---------------------------------------------------------------------
To unsubscribe, e-mail: lenya-user-unsubscribe@cocoon.apache.org
For additional commands, e-mail: lenya-user-help@cocoon.apache.org
Re: Wiki or documentation?
Posted by Rolf Kulemann <ro...@apache.org>.
On Fri, 2004-05-07 at 12:18, Thorsten Scherler wrote:
> Rolf Kulemann wrote:
>
> >Nice idea but a quite big approach which is imho worth to follow. Maybe
> >all this goes into direction of doco?
> >See http://wiki.cocoondev.org/Wiki.jsp?page=Doco .
> >
> >Maybe a good topic for a sprint.
> >
> >
> >
> Nice, Rolf!
> Jupp, I guess that doco would be the way to go!
>
> Sprint -> I would love to attend thus an event! Is it possible to be
> part of a sprint but not being e.g. in Zuerich (online)? I wouldn't mind
> hacking a weekend with you guys (I would love to)!
FYI:
I have more or less "green lights" from Uni here in Hannover to do a
sprint there....but since u are in spain...same problem for u to come to
Zurich. However, most Lenya people come from Zurich, so it makes sense
to do sprints there.
If it is an option to do Lenya sprints in germany, let me know.
--
Regards,
Rolf Kulemann
---------------------------------------------------------------------
To unsubscribe, e-mail: lenya-user-unsubscribe@cocoon.apache.org
For additional commands, e-mail: lenya-user-help@cocoon.apache.org
Attend the sprint virtually
Posted by Christian Egli <ch...@wyona.net>.
Thorsten Scherler <th...@juntadeandalucia.es> writes:
> Sprint -> I would love to attend thus an event! Is it possible to be
> part of a sprint but not being e.g. in Zuerich (online)? I wouldn't
> mind hacking a weekend with you guys (I would love to)!
We'll probably be on irc, so you should be able to meet us there
(http://cocoon.apache.org/lenya/community/irc.html)
--
Christian Egli christian.egli@wyona.net +41 1 272 9161
Wyona AG, Hardstrasse 219, CH-8005 Zurich
Open Source CMS http://www.wyona.org http://www.wyona.com
---------------------------------------------------------------------
To unsubscribe, e-mail: lenya-user-unsubscribe@cocoon.apache.org
For additional commands, e-mail: lenya-user-help@cocoon.apache.org
Re: Wiki or documentation?
Posted by Thorsten Scherler <th...@juntadeandalucia.es>.
Rolf Kulemann wrote:
>Nice idea but a quite big approach which is imho worth to follow. Maybe
>all this goes into direction of doco?
>See http://wiki.cocoondev.org/Wiki.jsp?page=Doco .
>
>Maybe a good topic for a sprint.
>
>
>
Nice, Rolf!
Jupp, I guess that doco would be the way to go!
Sprint -> I would love to attend thus an event! Is it possible to be
part of a sprint but not being e.g. in Zuerich (online)? I wouldn't mind
hacking a weekend with you guys (I would love to)!
King regards
Thorsten
--
Thorsten Scherler
---------------------------------------------------------------------
To unsubscribe, e-mail: lenya-user-unsubscribe@cocoon.apache.org
For additional commands, e-mail: lenya-user-help@cocoon.apache.org
Re: Wiki or documentation?
Posted by Rolf Kulemann <ro...@apache.org>.
On Fri, 2004-05-07 at 11:42, Thorsten Scherler wrote:
> [...]
> ...but anyway we could using lenya for that, not? I mean we can login
> and edit the docu with Kupu/BXE/... Of course that would mean that we
> have to extend the existing homepage with a community login module!
> ...but we could use the workflow for revision before publishing the
> changes. Would be a nice use case by the way ;-)
Nice idea but a quite big approach which is imho worth to follow. Maybe
all this goes into direction of doco?
See http://wiki.cocoondev.org/Wiki.jsp?page=Doco .
Maybe a good topic for a sprint.
--
Regards,
Rolf Kulemann
---------------------------------------------------------------------
To unsubscribe, e-mail: lenya-user-unsubscribe@cocoon.apache.org
For additional commands, e-mail: lenya-user-help@cocoon.apache.org
Re: Wiki or documentation?
Posted by Thorsten Scherler <th...@juntadeandalucia.es>.
Giampaolo/Trapo wrote:
> While i think that wiki2documentation needs something like a revisor
> who has a deep understand of lenya, automatic docu2wiki would not be a
> bad idea. Image this scenario:
>
> 1) docu2wiki giving something like doki ;) (or wicu)
> 2) people enhance doki using wiki style
> 3) the revisor decide which part of doki should used to update
> documentation
>
I agree with the revisor (that was the reason I mentioned a docu team).
Yes, the transformation cannot really be automatic (lets call it
semi-automatic) because at the end the docu team have to make sure
everything is kosher.
The doki seems to be "just" a wiki with a different name. ...and yes I
think that would be the way to go. I liked as well the idea that we put
all docus into wiki and work on them (Christian and Rolf mentioned that)!
...but anyway we could using lenya for that, not? I mean we can login
and edit the docu with Kupu/BXE/... Of course that would mean that we
have to extend the existing homepage with a community login module!
...but we could use the workflow for revision before publishing the
changes. Would be a nice use case by the way ;-)
King regards
--
Thorsten Scherler
---------------------------------------------------------------------
To unsubscribe, e-mail: lenya-user-unsubscribe@cocoon.apache.org
For additional commands, e-mail: lenya-user-help@cocoon.apache.org
Re: Wiki or documentation?
Posted by Giampaolo/Trapo <ne...@trapo.it>.
> Ok, I thought about that as well couple of days ago. I came to the
> conclusion that we need a wiki2documentation.xsl (and vice versa). I
> saw that somewhere in the net (have to find it again). I think that is
> maybe time to talk about a documentation team.
While i think that wiki2documentation needs something like a revisor who
has a deep understand of lenya, automatic docu2wiki would not be a bad
idea. Image this scenario:
1) docu2wiki giving something like doki ;) (or wicu)
2) people enhance doki using wiki style
3) the revisor decide which part of doki should used to update documentation
the advantages:
1) anyone can contribute
2) we partially avoid duplication of content
3) we can refer to already done subjects inside the doki
4) it's easier to look at changes
5) with FIXME tags we can point at which part of docu should be enhanced
of fixed.
Giampaolo/Trapo
---------------------------------------------------------------------
To unsubscribe, e-mail: lenya-user-unsubscribe@cocoon.apache.org
For additional commands, e-mail: lenya-user-help@cocoon.apache.org
Re: Wiki or documentation?
Posted by Christian Egli <ch...@wyona.net>.
Hi Thorsten
Thorsten Scherler <th...@juntadeandalucia.es> writes:
> Ok, I thought about that as well couple of days ago. I came to the
> conclusion that we need a wiki2documentation.xsl (and vice versa). I
> saw that somewhere in the net (have to find it again). I think that is
> maybe time to talk about a documentation team.
I don't think a wiki2documentation.xsl is needed, as the documentation
is done with forrest which has support for a wiki doctype
(http://xml.apache.org/forrest/wiki-sample.html). This means that you
can draft and consolidate it in wiki and then just simply move it to
the documentation in CVS.
--
Christian Egli christian.egli@wyona.net +41 1 272 9161
Wyona AG, Hardstrasse 219, CH-8005 Zurich
Open Source CMS http://www.wyona.org http://www.wyona.com
---------------------------------------------------------------------
To unsubscribe, e-mail: lenya-user-unsubscribe@cocoon.apache.org
For additional commands, e-mail: lenya-user-help@cocoon.apache.org
Re: Wiki or documentation?
Posted by Thorsten Scherler <th...@juntadeandalucia.es>.
Hi Giampaolo, hi users,
Giampaolo/Trapo wrote:
> Hi list,
>
> maybe this issue is a bit delicate. We all agree that documentation of
> the project is important as the projects itself (ie code) and that to
> get Lenya popular a good documentation is strategic.
:) Jupp, you are perfectly right
> However i see that in ml (and in irc channel as well) the wiki is
> referred more times than documentation. I try to wonder why:
> Wiki has FAQ,
> Wiki points to HowTos,
> Newbie feels that Wiki is more up to date than documentation,
> Simple update mechanism for committer.
Ok, that we are using the wiki heaps of time has the simple reason (for
me) that there normally is always browser but not a cvs access. The
second reason is that not everyone who wants to enhance the
documentation is a committer. We think that the concept user helps user
is best supported if we leave parts of the documentation open to the
user for enhancement.
Like you stated we refer more to the wiki then the doc because we think
by using the wiki the user can be easy part of the project because (s)he
has the possibility to modify the doc (wiki). ...and the user knows best
what their problem is (and maybe how the user solved it).
>
> Questions (maybe silly)
> how to get information on wiki consistent with documentation for this
> points of view:
> * definition and terms (not only the term itself but also how is
> displayed)
> * information itself
> * can documentation refer to specific pages of wiki and viceversa?
> * can documentation incorporated someway into wiki?
> * which should updated first?
>
Ok, I thought about that as well couple of days ago. I came to the
conclusion that we need a wiki2documentation.xsl (and vice versa). I saw
that somewhere in the net (have to find it again). I think that is maybe
time to talk about a documentation team.
...but anyway the logic way would be:
1) User has a problem
1a) User looks up wiki (there should be links to the documentation)
1b) User looks up the documentation
1c) User ask the mailinglist
2) User solves problem
2a) User gives feedback to the channel that help him solve the problem.
2b) If there is nothing in the documentation about the problem start a
wiki and post the link to the mailinglist and add it to
http://wiki.cocoondev.org/Wiki.jsp?page=Lenya
3) Before each new release we should run then the wiki2documentation.xsl
to merge the docs (ok will not be as simple ;-))
King regards
Thorsten
> Giampaolo/Trapo
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: lenya-user-unsubscribe@cocoon.apache.org
> For additional commands, e-mail: lenya-user-help@cocoon.apache.org
>
>
>
--
Thorsten Scherler
---------------------------------------------------------------------
To unsubscribe, e-mail: lenya-user-unsubscribe@cocoon.apache.org
For additional commands, e-mail: lenya-user-help@cocoon.apache.org
Re: Wiki or documentation?
Posted by Rolf Kulemann <ro...@apache.org>.
On Fri, 2004-05-07 at 09:36, Giampaolo/Trapo wrote:
> Hi list,
>
> maybe this issue is a bit delicate. We all agree that documentation of
> the project is important as the projects itself (ie code) and that to
> get Lenya popular a good documentation is strategic. However i see that
> in ml (and in irc channel as well) the wiki is referred more times than
> documentation. I try to wonder why:
> Wiki has FAQ,
> Wiki points to HowTos,
> Newbie feels that Wiki is more up to date than documentation,
> Simple update mechanism for committer.
Mhhh, if we generate docu from wiki, everybody could contribute docu.
>
> Questions (maybe silly)
> how to get information on wiki consistent with documentation for this
> points of view:
> * definition and terms (not only the term itself but also how is displayed)
> * information itself
> * can documentation refer to specific pages of wiki and viceversa?
Maybe it is a good idea to refer to wiki docs, but the drawback is, that
the wikis are only online viewable.
> * can documentation incorporated someway into wiki?
> * which should updated first?
I thought wiki is more a good "scratchpad" to start "docu". IMHO often
refered wiki docs, and wikis which describe elementary system behaviour
of Lenya should be "promoted" to the official docs.
Maybe there is a way to generate docu from wikis?
The advantage of wiki is
- easy to update/write
- Non committer's can write them
--
Regards,
Rolf Kulemann
---------------------------------------------------------------------
To unsubscribe, e-mail: lenya-user-unsubscribe@cocoon.apache.org
For additional commands, e-mail: lenya-user-help@cocoon.apache.org
Re: Wiki or documentation?
Posted by Chris Burdess <ch...@runtime-collective.com>.
Giampaolo/Trapo wrote:
> maybe this issue is a bit delicate. We all agree that documentation of
> the project is important as the projects itself (ie code) and that to
> get Lenya popular a good documentation is strategic. However i see
> that in ml (and in irc channel as well) the wiki is referred more
> times than documentation. I try to wonder why:
> Wiki has FAQ,
> Wiki points to HowTos,
> Newbie feels that Wiki is more up to date than documentation,
> Simple update mechanism for committer.
>
> Questions (maybe silly)
> how to get information on wiki consistent with documentation for this
> points of view:
> * definition and terms (not only the term itself but also how is
> displayed)
> * information itself
> * can documentation refer to specific pages of wiki and viceversa?
> * can documentation incorporated someway into wiki?
> * which should updated first?
Surely a reasonable goal of the project would to become self-hosting;
that is, replace the wiki with a lenya instance. If it's deemed too
cumbersome to use, you know what you have to fix.
---------------------------------------------------------------------
To unsubscribe, e-mail: lenya-user-unsubscribe@cocoon.apache.org
For additional commands, e-mail: lenya-user-help@cocoon.apache.org