forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <>
Subject Re: [PROPOSAL] A CMS for our Docs
Date Tue, 07 Jun 2005 08:04:20 GMT
Ross Gardler wrote:
> David Crossley wrote:
> >
> >How will the changed content get back into our SVN?
> For development, it doesn't. Daisy is fully version controlled (and I 
> think Lenya is). For publishing we do just as we are doing now.

I don't yet see the distinction. ASF projects have assets:
e.g. code, docs, etc. All assets are stored in SVN. So i would think
that the sources for all docs are stored in ASF repositories.

> >How is the workflow managed to get the content reviewed
> >and then published onto the website? At the moment we
> >do have a workflow of sorts.
> Any registered user can edit. Only committers can publish. The Forrest 
> generated site is only created from published changes.
> In other words, the same workflow as at present but we replace the edit 
> document/create patch/submit patch/review patch/apply patch process with 
> edit document/review edit/publish edit process.

Perhaps we are using different terminology here. I see that
committers review/edit and then "commit" changes. The "publish"
is a separate process whereby a group of committed edits
is now ready and the documents are generated and moved to the
actual website.

> >I also agree with Ferdinand. We would need a structure to
> >add these docs, or we end up with the un-manageable mess
> >that they call Wiki.

Clarification: When i said mess/Wiki then i did not specifically
mean Daisy or whatever. I refer to the problem where any user can
create a new document, which probably repeats content in other
documents. Most wikis that i have seen, have an unstructured
collection of repetitive documents.

> The idea is that the CMS is freeform like a wiki, but the published docs 
> only come from an Forrest generated site. In other words, we use the 
> Wiki to allow anyone to add content/edit content. We optimise the wiki 
> for the editors of content (as opposed to the users of content), that is 
> committers and technical users will likely use the Wiki as the primary 
> souce of documentation. Whilst users will use the published website.

What will actually happen is that users will come to this preparation
area to find the "most up-to-date docs". I suppose that we can have
big red warning banners.

> The published docs are managed using Forrest. Only those documents that 
> are of sufficient quality make it into the published docs that appear in 
> our distributions and on our website.

After that, how do those "finished" documents get edited again?

> In other words, we have the chaos of constantly evolving docs under the 
> surface, on the surface we have nice ordered, version controlled and 
> managed publications for our users. The migration path between the two 
> is the close attention to detali of the review process.

Oh dear, i am feeling overwhelmed with the thought of chaos.

> >Will we see sensible diffs, so that the committers can
> >oversee the content or do we get the voluminous diffs
> >like wiki where you cannot see what has been changed?
> >e.g. most paragraphs are one long line, so diffs are useless.
> Yes (at least for Daisy, don't know about Lenya). You can play around by 
> looking at the versions on Daisy home page at 

That helps a bit. What i was more concerned about is that diffs
need to come to a mailing list, because committers need to review
them as they come in. We cannot go off to a website to see if there
have been any changes.

Look at the diffs that come from Cocoon Wiki. Whenever there
is one long paragraph (common on a wiki) then email diffs
are impossible to monitor.

> >Who will be able to add content? Anyone? Do they need to
> >be a committer? Do they need to be on forrest-dev?
> My proposal is:
> 1) any visitor can add comments (see Comments link at bottom of 
> 2) any registered visitor can make edits, but their edits are not 
> published automaticall. People can self register but an email address 
> and confirmation email is used so we can tackle spammers

Not sure yet about the self-register thing. The day will come
when there is a disruptive person (perhaps well-intentioned) that
creates unnecessary work by continually changing stuff that they
do not understand.

> 3) any committer can publish edits
> 4) change emails will be sent to our existing commit email list 
> (although they can be sent to individual users)
> If we wanted a tighter control we can, of course have it, i.e. only 
> committers able to edit. But that would make it *harder* for 
> non-committers to contribute.
> >Are the contributions assigned copyright to ASF?
> We are currently discussing this over at Cocoon, the position seems to 
> be settling on:
> --- start of mail copied from Cocoon-dev ---
> > We can consider that a CLA is needed for "document committers" as 
> they control official (i.e. published) docs,
> +1
> > whereas "document contributors" are considered like people 
> contributing wiki pages and bugzilla patches, and implicitely accept 
> their contributions to be used by document committers under the ASL. A 
> way to ensure people don't miss this is a checkbox in the registration 
> screen stating "I accept my contributions to be used, modified or even 
> trashed by the documentation committers according to ASL 2.0".
> We could always add such verbiage to the registration screen, but I 
> would prefer not to do this in Daisy-proper. The registration form is 
> just a CForms form so that shouldn't be too hard - it's just something 
> we should remember when upgrading Daisy.
> --- end of copied mail ---
> >I actually far prefer the current process where people
> >need to send patches. That way they get reviewed by a committer.
> In this approach all I am proposing is we make it easier for people to 
> submit patches. I am not proposing that we remove the review stage, we 
> still have:
> edit -> draft -> review -> public/reject
> >Who will manage this Daisy installation? We cannot be stuck
> >with one person who knows a bit about it. We would need a
> >management plan. Same applies if we use Lenya.
> The Lenya team seem a more willing to work *with* us on integrating 
> Forrest and Daisy. I have discussed the Daisy plugin on the Daisy dev 
> list, I offered to donate the code to them and work on it over there 
> since they have static only publication and books on their roadmap (both 
> of which can be achieved with Daisy + Forrest). However, they were not 
> interested, preferring insted to build their own system that was not 
> dependant on Forrest. Since I need the multiple input formats of Forrest 
> that leaves me on my own here :-(

That does not sound very constructive. I thought that your suggestion was
that if a content managemnent system simply exposes the source, then
Forrest can process it. There is no "dependency".

> Gregor says (in another reply on this thread) that a number of the Lenya 
> team are willing to help us out. The concern I have is how easy it is to 
> integrate Forrest as the publication engine. I've tried and failed in 
> the past, but now I've figured out the locationmap maybe it will be 
> easier. Furthermore Lenya has moved on a fair bit since my last attempt.
> I'm willing to work on either platform. I have a client using Daisy, 
> that is the only reason for my preference. If we have the excplicit help 
> of the Lenya team here then I would happily work with Lenya, although my 
> time will not be as copious as it would be for Daisy (at least till 
> Lenya convinces me it is better and I sell a Lenya + Forrest system to 
> someone ;-)
> >I find this very alarming. Some people at Infrastructure are
> >trying to get a cross-project environment established for managing
> >documentation tools and site-building. All PMCs were asked to
> >join and discuss this. Some people have, but mainly the process
> >has stalled again.
> >
> >Instead we see projects like Cocoon rushing off to do their
> >own thing. Now we will get duplicate instances of Daisy/Forrest.
> It is my thinking that since Forrest is used by many projects within 
> Apache we should take it upon ourselves to develop and test a system 
> intended to be used across Apache. When we agree on how to do this we 
> should announce this on Infrastructure@a.o and invite interested parties 
> to come and help. As long as we have enough people committed here then 
> it will not matter if (when?) they do not come.

Lets try then. However i don't suggest "announcing" anything to
Infrastructure. There would surely be a requirement that has not
been addressed that sends us back to the drawing board. It would
be better to work with them.

> I'm offering some of my time (post 0.7) to get this going.
> Can we count on the Lenya team to assist?
> Thorsten, do you still need to create the Forrest Lenya integration? Can 
> we count on some of your time for that part of it?
> >Sorry, i am not trying to be obstructive, just that i see too
> >many unanswered issues.
> I understand. I've just had these same discussions (minus the infra@a.o 
> part) over at Cocoon so most of these issues have been discussed and 
> answered from the Cocoon perspective. Of course, that may be different 
> from the Forrest perspective.

Sounds like duplication of effort to me.


View raw message