Wiki

["C. Grobmeier" <gr...@possessed.de>]

Hi,

Forrest is in progress and i learned some cool thing about it last days. 
  I would like to enhance docs, but i have not an easy possibility to 
help. Many projects use a Wiki, and i am really glad about this. Many 
tips and "hidden" features i learned where only documented in the wikis.

I would like to suggest you to set up a wiki. I would like it very much. 
I hope i didn't miss this discussion.

If not, here should be more infos about this:
http://www.apache.org/dev/reporting-issues.html#new-wiki
if everybody likes this idea.

Cheers,
Chris.

Re: Wiki

[David Crossley <cr...@apache.org>]

C. Grobmeier wrote:
> 
> Forrest is in progress and i learned some cool thing about it last days. 
>  I would like to enhance docs, but i have not an easy possibility to 
> help. Many projects use a Wiki, and i am really glad about this. Many 
> tips and "hidden" features i learned where only documented in the wikis.

The Forrest project has decided not to use a wiki
at this stage of our development. Please see the mail
archives where the topic has been discussed a few times.

You do have the ability to help. All Forrest documentation
is included with the distribution:
http://forrest.apache.org/#status
Please edit existing docs or add new ones and send a patch.

-David

Re: Wiki

[Ross Gardler <rg...@apache.org>]

David Crossley wrote:
> Gav.... wrote:
>>> From: David Crossley
>>> C. Grobmeier wrote:
>>>> Gavin wrote:
>>>>> Here is one such thread :-
>>>>> http://marc.theaimsgroup.com/?l=forrest-dev&m=112277290808391&w=2
>>>>> Can't seem to find the one where I was involved at the moment,
>>>>> Will have another look later.
>>> Thanks. That links to some of the past discussion too.
>>>
>>> We need to review those threads, some great ideas evolved.
>>>
>>>> Thank you very much. I read it and understand, that you don't want a
>>>> wiki cause it's to early for this project. You fear that docs are in the
>>>> wiki but not in the core docs, that the PMC can't oversight the entries
>>>> and so on.
>>>>
>>>> I see a wiki more as a sandbox. It contents small artifacts of users who
>>>> don't want to get involved in the mailinglist or of users who don't want
>>>> to start creating a patch. Sometimes a wiki makes things easier. It
>>>> works for Commons and i think for Struts too.
>>>>
>>>> But i -really- don't want to bring this old discussion back to life
>>>> cause i am new to this project and hope to see your reasons more clearly
>>>> when i am deeper into it. I just was curious cause many projects use a
>>>> wiki but Forrest don't.
>>> Well one reason is our history and purpose. We are
>>> our own documentation system. Open your text editor,
>>> tweak our doc sources in site-author/ and review
>>> them with 'forrest run'. However we have received
>>> very few documentation patches.
>>>
>>> The above linked to an important proposal discussion
>>> which has not yet been implemented. Either use Lenya
>>> or piggyback on Cocoon's Daisy.
>>>  [PROPOSAL] A CMS for our Docs
>>>  http://thread.gmane.org/gmane.text.xml.forrest.devel/13450
>>>
>>> I glanced through that again. If someone could help to
>>> summarise it and make a new proposal, that would be
>>> fantastic.
>>>
>>> The Forrest project seems to be gaining some new energy
>>> these days, so perhaps we can move forward.
>> It was a very long group of threads that started off as a proposal
>> For Daisy to become the CMS of choice, it turned into how can we
>> Make Lenya + Forrest work together, Lenya as the CMS of course, then
>> Forrest would publish Lenya published (committer approved) docs.
>>
>> Hows that for a summary ? (er, only joking :) )
>>
>>

>> We have DOCO (DOCU ?) although I forget how far this has got and even
>> If this was its purpose.
>>
>> A summary would be good and I'll try and do one shortly, but as for making
>> it a new proposal, I am unsure as to what to propose, does it need yet
>> Another discussion considering advances in Lenya, Forrest etc have changed
>> How we might go about such an integration. The thread obviously chooses
>> Lenya for the CMS part, are we happy with that or do we need to go through
>> Some more choices again? Are Lenya in a position to be able to help again
>> Where necessary?
> 
> I waited for a while to see if some other people would comment.
> None, so i guess that means that people feel the same way as
> me about this topic: not enough energy for integration exercises.
> It sounds to me like there are not enough active developers here
> to enable it.

Sorry for my delayed response - been really busy in none Forrest things 
lately. Let me share my experiences and thoughts...

First of I wrote an HTMLEdit plugin that allowed Forrest sources to be 
edited from within a Forrest webapp. This worked really well and I used 
it quite a bit. But it was never community supported and I outgrew it 
and needed a CMS.

I then wrote the Daisy plugin, it works pretty well, in fact Cocoon 
currently uses it for their docs. However, it never attracted any 
interest from a wider community. The Daisy project were not interested 
as they didn't want to be dependant on Forrest for their static 
publishing. Cocoon adopted it, but have never contributed to its 
development and they now appear to be moving to a Maven based build 
process (including docs).

Another CMS related solution, although specifically for educational 
materials is the Eclipse plugin in the whiteboard. This code was brought 
over from my Burrokeet project which integrated standards compliant 
learning content into a Forrest generated site. However, I moved left 
this project a couple of years ago and very little has happened on 
either Burrokeet or Forrests Eclipse plugin.

There are devs here who are also devs at Lenya, hence the proposal of 
creating a Lenya plugin. Unfortunately nobody has found the time to 
realise that objective.

So, current integration of Forrest and a CMS is as good as dead in my 
opinion. But that doesn't mean it can't be revived there are plenty of 
good examples of how to go about it in our SVN history, of course these 
also contain examples of mistakes to avoid).

> If you want to pursue this, then perhaps just investigate
> a small part of it, e.g. one suggestion was to ask Cocoon
> if we could have a small section of their Daisy to use
> as a doc scratchpad, but leaving our main documentation
> as it is now.

This can be up and running with minimal effort since we already proved 
it works within Cocoon. But there are problems with this approach, 
performance being one of them (I can explain the technical reasons for 
this if anyone wants to pursue it, lets have a new subject for this though).

I'd love to explore all this in the context of my RT on Forrest 2. I 
don't have an immediate need for CMS integration, but I do have had some 
  thoughts about it with respect to the problems I identify in that 
thread (many of which come from my work integrating with Daisy and other 
applications at clients).

> Even with just that, there are still many issues to be
> investigated, e.g. restricted edit access, backup of sources,
> how to maintain oversight of diffs, define the exact purpose, etc.

important considerations, much of which I have answers for ;-)

> I don't want to squash your enthusiasm, but we don't want
> you spending effort if the rest of the project is not behind it.
> So it is a good idea of yours, to explore the high-level first.
> 
> Personally i would rather work with the doc system we have now
> and concentrate on the 0.8 release.

Yes, this is the same concern I have wrt my Forrest 2.0 RT. Having said 
that, a better doc system may help address the docs issues identified by 
others in that thread.

Ross

Re: Wiki

[David Crossley <cr...@apache.org>]

Gav.... wrote:
> > From: David Crossley
> > C. Grobmeier wrote:
> > > Gavin wrote:
> > > >Here is one such thread :-
> > > >http://marc.theaimsgroup.com/?l=forrest-dev&m=112277290808391&w=2
> > > >Can't seem to find the one where I was involved at the moment,
> > > >Will have another look later.
> > 
> > Thanks. That links to some of the past discussion too.
> > 
> > We need to review those threads, some great ideas evolved.
> > 
> > > Thank you very much. I read it and understand, that you don't want a
> > > wiki cause it's to early for this project. You fear that docs are in the
> > > wiki but not in the core docs, that the PMC can't oversight the entries
> > > and so on.
> > >
> > > I see a wiki more as a sandbox. It contents small artifacts of users who
> > > don't want to get involved in the mailinglist or of users who don't want
> > > to start creating a patch. Sometimes a wiki makes things easier. It
> > > works for Commons and i think for Struts too.
> > >
> > > But i -really- don't want to bring this old discussion back to life
> > > cause i am new to this project and hope to see your reasons more clearly
> > > when i am deeper into it. I just was curious cause many projects use a
> > > wiki but Forrest don't.
> > 
> > Well one reason is our history and purpose. We are
> > our own documentation system. Open your text editor,
> > tweak our doc sources in site-author/ and review
> > them with 'forrest run'. However we have received
> > very few documentation patches.
> > 
> > The above linked to an important proposal discussion
> > which has not yet been implemented. Either use Lenya
> > or piggyback on Cocoon's Daisy.
> >  [PROPOSAL] A CMS for our Docs
> >  http://thread.gmane.org/gmane.text.xml.forrest.devel/13450
> > 
> > I glanced through that again. If someone could help to
> > summarise it and make a new proposal, that would be
> > fantastic.
> >
> > The Forrest project seems to be gaining some new energy
> > these days, so perhaps we can move forward.
> 
> It was a very long group of threads that started off as a proposal
> For Daisy to become the CMS of choice, it turned into how can we
> Make Lenya + Forrest work together, Lenya as the CMS of course, then
> Forrest would publish Lenya published (committer approved) docs.
> 
> Hows that for a summary ? (er, only joking :) )
> 
> 
> We have DOCO (DOCU ?) although I forget how far this has got and even
> If this was its purpose.
> 
> A summary would be good and I'll try and do one shortly, but as for making
> it a new proposal, I am unsure as to what to propose, does it need yet
> Another discussion considering advances in Lenya, Forrest etc have changed
> How we might go about such an integration. The thread obviously chooses
> Lenya for the CMS part, are we happy with that or do we need to go through
> Some more choices again? Are Lenya in a position to be able to help again
> Where necessary?

I waited for a while to see if some other people would comment.
None, so i guess that means that people feel the same way as
me about this topic: not enough energy for integration exercises.
It sounds to me like there are not enough active developers here
to enable it.

Gav, don't take it on lightly, there are many issues.

Look at the archives to see how other people have done
past proposals (they usually have [Proposal] in the Subject).
Generally one person has a burning desire and puts in a lot
of effort to explore the topic and figure out exactly what
needs to be done. A well thought-out proposal enables concise
followup discussion.

If you want to pursue this, then perhaps just investigate
a small part of it, e.g. one suggestion was to ask Cocoon
if we could have a small section of their Daisy to use
as a doc scratchpad, but leaving our main documentation
as it is now.

Even with just that, there are still many issues to be
investigated, e.g. restricted edit access, backup of sources,
how to maintain oversight of diffs, define the exact purpose, etc.

I don't want to squash your enthusiasm, but we don't want
you spending effort if the rest of the project is not behind it.
So it is a good idea of yours, to explore the high-level first.

Personally i would rather work with the doc system we have now
and concentrate on the 0.8 release.

-David

RE: Wiki

["Gav...." <br...@brightontown.com.au>]

> -----Original Message-----
> From: David Crossley [mailto:crossley@apache.org]
> Sent: Friday, 3 November 2006 3:55 PM
> To: dev@forrest.apache.org
> Subject: Re: Wiki
> 
> C. Grobmeier wrote:
> > Gavin wrote:
> > >Here is one such thread :-
> > >http://marc.theaimsgroup.com/?l=forrest-dev&m=112277290808391&w=2
> > >Can't seem to find the one where I was involved at the moment,
> > >Will have another look later.
> 
> Thanks. That links to some of the past discussion too.
> 
> We need to review those threads, some great ideas evolved.
> 
> > Thank you very much. I read it and understand, that you don't want a
> > wiki cause it's to early for this project. You fear that docs are in the
> > wiki but not in the core docs, that the PMC can't oversight the entries
> > and so on.
> >
> > I see a wiki more as a sandbox. It contents small artifacts of users who
> > don't want to get involved in the mailinglist or of users who don't want
> > to start creating a patch. Sometimes a wiki makes things easier. It
> > works for Commons and i think for Struts too.
> >
> > But i -really- don't want to bring this old discussion back to life
> > cause i am new to this project and hope to see your reasons more clearly
> > when i am deeper into it. I just was curious cause many projects use a
> > wiki but Forrest don't.
> 
> Well one reason is our history and purpose. We are
> our own documentation system. Open your text editor,
> tweak our doc sources in site-author/ and review
> them with 'forrest run'. However we have received
> very few documentation patches.
> 
> The above linked to an important proposal discussion
> which has not yet been implemented. Either use Lenya
> or piggyback on Cocoon's Daisy.
>  [PROPOSAL] A CMS for our Docs
>  http://thread.gmane.org/gmane.text.xml.forrest.devel/13450
> 
> I glanced through that again. If someone could help to
> summarise it and make a new proposal, that would be
> fantastic.

It was a very long group of threads that started off as a proposal
For Daisy to become the CMS of choice, it turned into how can we
Make Lenya + Forrest work together, Lenya as the CMS of course, then
Forrest would publish Lenya published (committer approved) docs.

Hows that for a summary ? (er, only joking :) )


We have DOCO (DOCU ?) although I forget how far this has got and even
If this was its purpose.

A summary would be good and I'll try and do one shortly, but as for making
it a new proposal, I am unsure as to what to propose, does it need yet
Another discussion considering advances in Lenya, Forrest etc have changed
How we might go about such an integration. The thread obviously chooses
Lenya for the CMS part, are we happy with that or do we need to go through
Some more choices again? Are Lenya in a position to be able to help again
Where necessary?

Gav...

> 
> The Forrest project seems to be gaining some new energy
> these days, so perhaps we can move forward.
> 
> -David
> 
> 
> --
> No virus found in this incoming message.
> Checked by AVG Free Edition.
> Version: 7.1.409 / Virus Database: 268.13.24/514 - Release Date: 11/2/2006

Re: Wiki

[David Crossley <cr...@apache.org>]

C. Grobmeier wrote:
> Gavin wrote:
> >Here is one such thread :-
> >http://marc.theaimsgroup.com/?l=forrest-dev&m=112277290808391&w=2
> >Can't seem to find the one where I was involved at the moment, 
> >Will have another look later.

Thanks. That links to some of the past discussion too.

We need to review those threads, some great ideas evolved.

> Thank you very much. I read it and understand, that you don't want a 
> wiki cause it's to early for this project. You fear that docs are in the 
> wiki but not in the core docs, that the PMC can't oversight the entries 
> and so on.
>
> I see a wiki more as a sandbox. It contents small artifacts of users who 
> don't want to get involved in the mailinglist or of users who don't want 
> to start creating a patch. Sometimes a wiki makes things easier. It 
> works for Commons and i think for Struts too.
> 
> But i -really- don't want to bring this old discussion back to life 
> cause i am new to this project and hope to see your reasons more clearly 
> when i am deeper into it. I just was curious cause many projects use a 
> wiki but Forrest don't.

Well one reason is our history and purpose. We are
our own documentation system. Open your text editor,
tweak our doc sources in site-author/ and review
them with 'forrest run'. However we have received
very few documentation patches.

The above linked to an important proposal discussion
which has not yet been implemented. Either use Lenya
or piggyback on Cocoon's Daisy.
 [PROPOSAL] A CMS for our Docs
 http://thread.gmane.org/gmane.text.xml.forrest.devel/13450

I glanced through that again. If someone could help to
summarise it and make a new proposal, that would be
fantastic.

The Forrest project seems to be gaining some new energy
these days, so perhaps we can move forward.

-David

Re: Wiki

["C. Grobmeier" <gr...@possessed.de>]

> Here is one such thread :-
> http://marc.theaimsgroup.com/?l=forrest-dev&m=112277290808391&w=2
> Can't seem to find the one where I was involved at the moment, 
> Will have another look later.

Thank you very much. I read it and understand, that you don't want a 
wiki cause it's to early for this project. You fear that docs are in the 
wiki but not in the core docs, that the PMC can't oversight the entries 
and so on.

I see a wiki more as a sandbox. It contents small artifacts of users who 
don't want to get involved in the mailinglist or of users who don't want 
to start creating a patch. Sometimes a wiki makes things easier. It 
works for Commons and i think for Struts too.

But i -really- don't want to bring this old discussion back to life 
cause i am new to this project and hope to see your reasons more clearly 
when i am deeper into it. I just was curious cause many projects use a 
wiki but Forrest don't.

Thanks,
Chris.

RE: Wiki

["Gav...." <br...@brightontown.com.au>]

Hi Chris, 

Here is one such thread :-

http://marc.theaimsgroup.com/?l=forrest-dev&m=112277290808391&w=2

Can't seem to find the one where I was involved at the moment, 
Will have another look later.

Gav...

> -----Original Message-----
> From: C. Grobmeier [mailto:grobmeier@possessed.de]
> Sent: Friday, 3 November 2006 6:34 AM
> To: dev@forrest.apache.org
> Subject: Re: Wiki
> 
> > Forrest is for documentation, it would seem ironic that docs for it were
> > Stored elsewhere. All documentation therefore is stored on the forrest
> > Site. There is nothing to hide, if a feature exists that is not
> documented
> > then we need to document it on the main site.
> >
> >> I would like to suggest you to set up a wiki. I would like it very
> much.
> >> I hope i didn't miss this discussion.
> >
> > There has been a few discussions about it in the past. I myself brought
> > It up about a year a go. I now understand better why we do not use one.
> 
> Sorry to hear that. Didn't want to bring this discussion back to life.
> 
> > Please, post here or to Jira what new docs you have and we'll see about
> > Adding it.
> 
> I'll do and search the archives for your thread.
> 
> Cheers,
> Chris
> 
> 
> --
> No virus found in this incoming message.
> Checked by AVG Free Edition.
> Version: 7.1.409 / Virus Database: 268.13.24/514 - Release Date: 11/2/2006

Re: Wiki

["C. Grobmeier" <gr...@possessed.de>]

> Forrest is for documentation, it would seem ironic that docs for it were
> Stored elsewhere. All documentation therefore is stored on the forrest
> Site. There is nothing to hide, if a feature exists that is not documented
> then we need to document it on the main site.
> 
>> I would like to suggest you to set up a wiki. I would like it very much.
>> I hope i didn't miss this discussion.
> 
> There has been a few discussions about it in the past. I myself brought
> It up about a year a go. I now understand better why we do not use one.

Sorry to hear that. Didn't want to bring this discussion back to life.

> Please, post here or to Jira what new docs you have and we'll see about
> Adding it.

I'll do and search the archives for your thread.

Cheers,
Chris

RE: Wiki

["Gav...." <br...@brightontown.com.au>]

Hi Chris,

> -----Original Message-----
> From: C. Grobmeier [mailto:grobmeier@possessed.de]
> Sent: Friday, 3 November 2006 1:22 AM
> To: dev@forrest.apache.org
> Subject: Wiki
> 
> Hi,
> 
> Forrest is in progress and i learned some cool thing about it last days.
>   I would like to enhance docs, but i have not an easy possibility to
> help. 

It should be easy enough to add a jira issue -
https://issues.apache.org/jira/browse/FOR

Many projects use a Wiki, and i am really glad about this. Many
> tips and "hidden" features i learned where only documented in the wikis.

Forrest is for documentation, it would seem ironic that docs for it were
Stored elsewhere. All documentation therefore is stored on the forrest
Site. There is nothing to hide, if a feature exists that is not documented
then we need to document it on the main site.

> 
> I would like to suggest you to set up a wiki. I would like it very much.
> I hope i didn't miss this discussion.

There has been a few discussions about it in the past. I myself brought
It up about a year a go. I now understand better why we do not use one.


Please, post here or to Jira what new docs you have and we'll see about
Adding it.

Thanks

Gav...

> 
> If not, here should be more infos about this:
> http://www.apache.org/dev/reporting-issues.html#new-wiki
> if everybody likes this idea.
> 
> Cheers,
> Chris.
> 
> 
> --
> No virus found in this incoming message.
> Checked by AVG Free Edition.
> Version: 7.1.409 / Virus Database: 268.13.22/512 - Release Date: 11/1/2006