You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Steven Noels <st...@outerthought.org> on 2005/05/13 11:51:16 UTC
Forrest & Daisy integration scenarios
On 12 May 2005, at 17:21, Stefano Mazzocchi wrote:
> But it's also true that editing xml files in a svn repository sucks as
> an editing tool. Using wiki (or daisy or other solutions) is much
> better.
>
> I like the notion of
>
> daisy -> forrest -> out
>
> makes very good sense.
It does, yet there's obvious huge bits of overlap between Forrest and
Daisy's publishing mechanism. IMO, Daisy is perfectly able to host
Cocoon's documentation, both for editing and publishing.
The bridge between Daisy and Forrest could be a Forrest exporter: i.e.
a tool which aggregates and renders a Daisy site and converts it into a
Forrest source xdocs + site.xml tree. This tool might find some of its
inspiration in the work we're planning for the Daisy Books tool.
If however the Cocoon documentation only consists of Daisy-managed
content, I wonder what this exporter would buy us in the short term
compared with a live Daisy site + custom skin, possibly wget-ed into
static HTML for SVN storage.
There's a few possible scenarios:
------------------------------
-------| editing wiki (plain daisy) | (1)
-------- | ------------------------------
| repo |----|
-------- | ---------------------------------- wget
---------------
-------| wiki + custom cocoon-site skin |----------| static
HTML | (2)
| ----------------------------------
---------------
|
| ---------------------------------------- wget
---------------
-------| publish-only lib + custom render app |----------|
static HTML | (3)
| ----------------------------------------
---------------
|
| -------------------- forrest ---------------
-------| forrest exporter |-------------| static HTML | (4)
-------------------- ---------------
(1) exists already, (2) is low-hanging fruit, (3) is something we're
working on for the next release, and (4) is possible as well, but
requires more work.
In (2), I consider the wget step to be optional for the live Cocoon
documentation site, and only required when we want to produce static
HTML for inclusion in the distribution, or if we want to store the
site's content in SVN as well. Both make sense to me.
In the current Daisy Forrest plugin, the interface between Forrest and
Daisy is a rendered, jtidied Wiki page. That (a) is not a very solid
contract IMHO, and (b) creates duplication of effort, as the site
structure needs to be maintained in both Daisy and Forrest.
Of course, if the Cocoon documentation would be a mixture of Daisy- and
non-Daisy managed documents (like Word/OO files), we would need to come
up with other scenarios.
What do people think?
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source Java & XML An Orixo Member
Read my weblog at http://blogs.cocoondev.org/stevenn/
stevenn at outerthought.org stevenn at apache.org
Re: Forrest & Daisy integration scenarios
Posted by Steven Noels <st...@outerthought.org>.
On 13 May 2005, at 12:30, Sylvain Wallez wrote:
> IMO the problem is more political or sentimental than technical.
Yes, and that's why I won't push. But I'm feeling our pain.
> Note that I don't question the value of Daisy nor the good intentions
> of you OT folks, but I want to point out the non-technical problems.
> We may also question ourselves about using Lenya.
I believe there are no other points than non-technical ones.
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source Java & XML An Orixo Member
Read my weblog at http://blogs.cocoondev.org/stevenn/
stevenn at outerthought.org stevenn at apache.org
Re: Forrest & Daisy integration scenarios
Posted by Ross Gardler <rg...@apache.org>.
Sylvain Wallez wrote:
> Steven Noels wrote:
>
>> On 12 May 2005, at 17:21, Stefano Mazzocchi wrote:
>>
>>> But it's also true that editing xml files in a svn repository sucks
>>> as an editing tool. Using wiki (or daisy or other solutions) is much
>>> better.
>>>
>>> I like the notion of
>>>
>>> daisy -> forrest -> out
>>>
>>> makes very good sense.
>>
>>
>>
>> It does, yet there's obvious huge bits of overlap between Forrest and
>> Daisy's publishing mechanism. IMO, Daisy is perfectly able to host
>> Cocoon's documentation, both for editing and publishing.
>
>
>
> <snip/>
>
>> What do people think?
>
>
>
> IMO the problem is more political or sentimental than technical.
>
> Although Daisy seems to fulfill a need that has no satisfying answer
> today to write and manage content, we're quite happy with the
> Forrest-based publication process. So why would we want to trash what
> works and is using an Apache project in favor of another tool?
For me, Daisy provides a superb editing environment that lowers the
barrier to entry for doc writers significantly. It also has enough
workflow and version management in it to manage the doc authoring
process. Finally, it is Cocoon based and Apache Licensed so can be
enhanced by Cocoon devs if required. I believe the separation of
repository from editing environement is key to this flexibility (and
where daisy wins hands down over the current alternative Cocoon CMS, Lenya)
What Daisy (nor Lenya) does not do is integrate content from multiple
sources. This is important because the reality of Cocoon (and
incidentally all businesses/projects) is that they have docs all over
the place in many different formats (PDF, word, OOo, Xdoc, HTMl, mail,
wiki etc.) and repositories (mailarchives, svn, network file systems,
http servers etc.). If we want the lowest barrier to entry for doc
writers then we have to allow them to submit docs in any format and via
whatever means is most comfotable to them.
In other words, I am not talking about a tool for *writing* docs, I'm
taling about a tool for collating quality docs into an official
documentation colelction.
With respect to tools for *writing* docs I agree with Nicola, we need
doc writers not tools. That being siad, I would advocate Daisy as the
"official" tool of the Cocoon project (to replace the existing wiki).
I advocate Daisy because is Cocoon based, therefore it sends the right
message and is cuastomisable by Cocoon committers. However, it is worth
noting that Thorsten (a Forrest and Lenya committer) is hoping to build
a Lenya plugin for Forrest. So everything I say in these threads
regarding Forrest + Daisy, could also be said of Forrest + Lenya once he
has that plugin working.
Ross
Re: Forrest & Daisy integration scenarios
Posted by Sylvain Wallez <sy...@apache.org>.
Steven Noels wrote:
> On 12 May 2005, at 17:21, Stefano Mazzocchi wrote:
>
>> But it's also true that editing xml files in a svn repository sucks
>> as an editing tool. Using wiki (or daisy or other solutions) is much
>> better.
>>
>> I like the notion of
>>
>> daisy -> forrest -> out
>>
>> makes very good sense.
>
>
> It does, yet there's obvious huge bits of overlap between Forrest and
> Daisy's publishing mechanism. IMO, Daisy is perfectly able to host
> Cocoon's documentation, both for editing and publishing.
<snip/>
> What do people think?
IMO the problem is more political or sentimental than technical.
Although Daisy seems to fulfill a need that has no satisfying answer
today to write and manage content, we're quite happy with the
Forrest-based publication process. So why would we want to trash what
works and is using an Apache project in favor of another tool?
Note that I don't question the value of Daisy nor the good intentions of
you OT folks, but I want to point out the non-technical problems. We may
also question ourselves about using Lenya.
And Drupal and other PHP-based systems are IMO a dead end from a
community acceptance POV (unless they are recommended by the ASF
infrastructure): why would Cocoon use a PHP CMS when it is itself used
to build large CMSes around the world?
These community and dogfood issues are IMO the main reasons of the
current state of our doc system, much more than the technical ones.
Sylvain
--
Sylvain Wallez Anyware Technologies
http://apache.org/~sylvain http://anyware-tech.com
Apache Software Foundation Member Research & Technology Director
Re: [daisy] Forrest & Daisy integration scenarios
Posted by Ross Gardler <rg...@apache.org>.
Steven Noels wrote:
> On 12 May 2005, at 17:21, Stefano Mazzocchi wrote:
>
>> But it's also true that editing xml files in a svn repository sucks as
>> an editing tool. Using wiki (or daisy or other solutions) is much better.
>>
>> I like the notion of
>>
>> daisy -> forrest -> out
>>
>> makes very good sense.
>
>
> It does, yet there's obvious huge bits of overlap between Forrest and
> Daisy's publishing mechanism. IMO, Daisy is perfectly able to host
> Cocoon's documentation, both for editing and publishing.
There is overlap, but Forrest is, in my opinion, far superior in the
flexibility of its publishing and has the added ability to integrate
content from multiple sources and make it available in multiple formats.
Since the cocoon docs already consist of Wiki docs, Xdocs, HTML docs,
Daisy docs and who knows what else this ability to utilise multiple
input formats is critical.
> The bridge between Daisy and Forrest could be a Forrest exporter: i.e. a
> tool which aggregates and renders a Daisy site and converts it into a
> Forrest source xdocs + site.xml tree. This tool might find some of its
> inspiration in the work we're planning for the Daisy Books tool.
As Steven will probably know I recently started a thread about this and
other related areas over on the Daisy dev list. We'll see where that goes.
> If however the Cocoon documentation only consists of Daisy-managed
> content,
It doesn't, and I doubt it ever will.
> I wonder what this exporter would buy us in the short term
> compared with a live Daisy site + custom skin, possibly wget-ed into
> static HTML for SVN storage.
Pulling together all the different content available and making it uniform.
Allowing the different content to be presented in many different way
(without having to write new custom skins).
Allowing multiple content objects to be built for different types of
reader (technical, novice, marketing, developer etc.)
Producing a static site that can be downloaded and installed on a users
machine.
(I'm sure there are more... )
> There's a few possible scenarios:
>
> ------------------------------
> -------| editing wiki (plain daisy) | (1)
> -------- | ------------------------------
> | repo |----|
> -------- | ---------------------------------- wget
> ---------------
> -------| wiki + custom cocoon-site skin |----------| static
> HTML | (2)
> | ----------------------------------
> ---------------
> |
> | ---------------------------------------- wget
> ---------------
> -------| publish-only lib + custom render app |----------|
> static HTML | (3)
> | ----------------------------------------
> ---------------
> |
> | -------------------- forrest ---------------
> -------| forrest exporter |-------------| static HTML | (4)
> -------------------- ---------------
>
> (1) exists already, (2) is low-hanging fruit, (3) is something we're
> working on for the next release, and (4) is possible as well, but
> requires more work.
Daisy + Forrest gives (3) now (see discussion on daisy dev list).
(4) is very nearly here, needs a little more work on the Daisy plugin
for Forrest, but it's not much (at least I don't believe so, I've not
thought long and hard about it)
(see my proposal
http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=111591833106339&w=2 ,
for another possible scenario)
> In the current Daisy Forrest plugin, the interface between Forrest and
> Daisy is a rendered, jtidied Wiki page. That (a) is not a very solid
> contract IMHO, and (b) creates duplication of effort, as the site
> structure needs to be maintained in both Daisy and Forrest.
(a) is for discussion either on the Daisy list or the Forrest list. I'd
be interested to hear your concerns, the plugin is merely
a whiteboard proof of concept so feedback is positively encouraged.
(b) is incorrect. You only need to maintain the site structure
separately if you want the structure to be separate. The current plugin
works this way because that is the use case I have - mixing content from
multiple input sources means it is impossible to use the Daisy
navigation editor. Besides I prefer *not* to use the Daisy navigation
editor as it is cumbersome since it is a web based system. I have a Drag
and Drop GUI editor (http://www.burrokeet.org ) that I use to maintain
site structure.
This allows the Daisy navigation to be optimised for content editors
rather than content readers.
It also allows multiple content objects to be designed from the various
sources. That is, different collections of documents targeted
at different readers (novice, developer, marketing, press etc.)
Having said all that, if required, it is trivial to make Forrest use the
Daisy defined navigation if that is what is needed. It merely requires
an XSL transformation of the Daisy navigation doc.
> Of course, if the Cocoon documentation would be a mixture of Daisy- and
> non-Daisy managed documents (like Word/OO files), we would need to come
> up with other scenarios.
See my proposal yesterday,
http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=111591833106339&w=2
Ross
_______________________________________________
daisy mailing list
daisy@lists.cocoondev.org
http://lists.cocoondev.org/mailman/listinfo/daisy
Re: Forrest & Daisy integration scenarios
Posted by Ross Gardler <rg...@apache.org>.
Sebastien Arbogast wrote:
>>What we need is simplicity in the workflow.
>>
>>Simplify the workflow, tuning the simplicity to those people that are
>>more likely to write, and content will start flowing in (as the wiki
>>shows very well).
..
> So I think that there is a third criteria we have to integrate in our
> design of a better documentation system : of course adapting it to
> users and to potential writers is essential, but let's not forget to
> integrate document type in the process.
I agree toatlly with the both of you. This is why I advocate Daisy +
Cocoon. Daisy can handle binday files, Forrest can publish them
seemlessly in the main site.
I see Stefano's call for "get it done", expect a simple demo tonight (GMT).
Ross
Re: Forrest & Daisy integration scenarios
Posted by Sebastien Arbogast <se...@gmail.com>.
> What we need is simplicity in the workflow.
>
> Simplify the workflow, tuning the simplicity to those people that are
> more likely to write, and content will start flowing in (as the wiki
> shows very well).
>
> Sebastien, this is not a funny discussion. Those who think that Word is
> always more productive than Latex have never written a 200 pages math book.
I understand what you mean as I intensively use Latex and Docbook
myself to write my articles and reports. But the thing is : do you
really expect a 200 pages technical book to show up in Cocoon
documentation ? Do you really think anyone will be crazy enough to try
that (I've already been that crazy to think we could do that with
Cocoon In Action), whether with WYSIWYG or any other mean ?
So I think that there is a third criteria we have to integrate in our
design of a better documentation system : of course adapting it to
users and to potential writers is essential, but let's not forget to
integrate document type in the process.
--
Sebastien ARBOGAST
Re: Forrest & Daisy integration scenarios
Posted by Stefano Mazzocchi <st...@apache.org>.
Sebastien Arbogast wrote:
>>>I think that we need people that write documentation, not a tool.
>>
>>I can hardly disagree more.
>>
>>I wrote my blog *before* I wrote its posts. Without it, I could have
>>written them by hand, but god, that always made me go "nah".
>
>
> MDR ! This discussion is really funny. No offense guys but I feel like
> I see my grandparents in front of me saying "In my time, things were
> better, we wrote our letters by hand and then we used a typewriter to
> make it cleaner..."
>
> WYSIWYG guys ! WYSIWYG ! And so many things instead of the "G" at the
> end can be achieved now :
> What You See Is What You...
> - Get
> - Structure
> - Meant
> and the closer we'll get to the "What You See Is What You THINK", the
> easier it will be to create any digital content. Isn't it what all the
> computer thing is all about ?
What we need is simplicity in the workflow.
Simplify the workflow, tuning the simplicity to those people that are
more likely to write, and content will start flowing in (as the wiki
shows very well).
Sebastien, this is not a funny discussion. Those who think that Word is
always more productive than Latex have never written a 200 pages math book.
In short: simplicity of workflow is the goal, not WYSIWI*. WYSIWI*, if
done properly, is a way to achieve it, but it has to be carefully tuned
for the needs of the users we are targetting.
--
Stefano.
Re: Forrest & Daisy integration scenarios
Posted by Sebastien Arbogast <se...@gmail.com>.
> > I think that we need people that write documentation, not a tool.
>
> I can hardly disagree more.
>
> I wrote my blog *before* I wrote its posts. Without it, I could have
> written them by hand, but god, that always made me go "nah".
MDR ! This discussion is really funny. No offense guys but I feel like
I see my grandparents in front of me saying "In my time, things were
better, we wrote our letters by hand and then we used a typewriter to
make it cleaner..."
WYSIWYG guys ! WYSIWYG ! And so many things instead of the "G" at the
end can be achieved now :
What You See Is What You...
- Get
- Structure
- Meant
and the closer we'll get to the "What You See Is What You THINK", the
easier it will be to create any digital content. Isn't it what all the
computer thing is all about ?
--
Sebastien ARBOGAST
Re: Forrest & Daisy integration scenarios
Posted by Stefano Mazzocchi <st...@apache.org>.
Nicola Ken Barozzi wrote:
> Steven Noels wrote:
> ...
>
>> What do people think?
>
>
> I think that we need people that write documentation, not a tool.
I can hardly disagree more.
I wrote my blog *before* I wrote its posts. Without it, I could have
written them by hand, but god, that always made me go "nah".
--
Stefano.
Re: Forrest & Daisy integration scenarios
Posted by Sylvain Wallez <sy...@apache.org>.
Nicola Ken Barozzi wrote:
> Steven Noels wrote:
> ...
>
>> What do people think?
>
>
> I think that we need people that write documentation, not a tool.
>
> I'll think about it again when we have 10 doc writers sending patches
> and files that we are not able to manage.
We'll never have 10 doc writers without tools that ease the doc writing
task...
> For now converting all documentation files to plain html and adding a
> link from every page to the svn version would certainly make things
> easy enough for most doc writers.
Yes, that would be better than what we have today, but won't ease the
contribution/validation/publication workflow.
Sylvain
--
Sylvain Wallez Anyware Technologies
http://apache.org/~sylvain http://anyware-tech.com
Apache Software Foundation Member Research & Technology Director
Re: Forrest & Daisy integration scenarios
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Steven Noels wrote:
...
> Again, I'm not pushing - consider me a dis-interested, yet friendly
> party. I'm quite convinced though that documentation committers are
> currently passively discouraged by the patch/mail mechanism.
>
> Remember what started the Cocoon Wiki? Content (Leigh Dodds) + platform
> (JSPWiki). Leigh had valuable content to offer, and the format was a
> mere side effect of his preferred authoring tool.
Hmmm... I guess I'm wrong, and the current system is a too high barrier
to entry: the wiki example is a good one.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: Forrest & Daisy integration scenarios
Posted by Steven Noels <st...@outerthought.org>.
On 13 May 2005, at 17:44, Bertrand Delacretaz wrote:
> Problem is, ATM I don't think anyone has a sizeable chunk of
> up-to-date consistent content to contribute. I'd love to be proven
> wrong though.
>
> If someone could come up with that (in any structured format - we do
> conversions don't we?), I'd be all for starting to use Daisy to create
> "editorial" (as opposed to generated) docs, and would volunteer to
> help administer it if needed. But until this sizeable chunk exists,
> setting up new tools might be a waste of time.
Very valid point. Two thoughts:
* move the exiting xdoc-based documentation into Daisy, so that folks
have something to start working from (requires a huge leap of faith, I
know)
* loose ties and integration: let's not try to design an
all-encompassing process/system for generated, editorial, contributed,
imagined and whatever kind of other information/documentation - we have
the luxury of working with the web which makes integration of disparate
processes and tools a matter of wget/mod_rewrite/mod_proxy and
whatelse. As long as all tools produce wget-able, visually-united
webpages, we can generate something which is up for automated static
publication.
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source Java & XML An Orixo Member
Read my weblog at http://blogs.cocoondev.org/stevenn/
stevenn at outerthought.org stevenn at apache.org
Re: Forrest & Daisy integration scenarios
Posted by Bertrand Delacretaz <bd...@apache.org>.
Le 13 mai 05, à 12:36, Steven Noels a écrit :
> ...I'm quite convinced though that documentation committers are
> currently passively discouraged by the patch/mail mechanism...
Sounds right.
But there is another part of our docs which is still incomplete: the
autogenerated reference docs, created (mostly) from javadoc-like tags.
IIRC (but I haven't checked recently) the mechanism is working, someone
"just" needs to check that it is applied consistently to all
components, and add "some" explanations in javadocs.
> ...Remember what started the Cocoon Wiki? Content (Leigh Dodds) +
> platform (JSPWiki). Leigh had valuable content to offer, and the
> format was a mere side effect of his preferred authoring tool...
Very true.
Problem is, ATM I don't think anyone has a sizeable chunk of up-to-date
consistent content to contribute. I'd love to be proven wrong though.
If someone could come up with that (in any structured format - we do
conversions don't we?), I'd be all for starting to use Daisy to create
"editorial" (as opposed to generated) docs, and would volunteer to help
administer it if needed. But until this sizeable chunk exists, setting
up new tools might be a waste of time.
-Bertrand
Re: Forrest & Daisy integration scenarios
Posted by Steven Noels <st...@outerthought.org>.
On 13 May 2005, at 12:01, Nicola Ken Barozzi wrote:
> Steven Noels wrote:
> ...
>> What do people think?
>
> I think that we need people that write documentation, not a tool.
Of course, that's why I'm suggesting to take a look at the low-hanging
fruit.
> I'll think about it again when we have 10 doc writers sending patches
> and files that we are not able to manage.
Again, I'm not pushing - consider me a dis-interested, yet friendly
party. I'm quite convinced though that documentation committers are
currently passively discouraged by the patch/mail mechanism.
Remember what started the Cocoon Wiki? Content (Leigh Dodds) + platform
(JSPWiki). Leigh had valuable content to offer, and the format was a
mere side effect of his preferred authoring tool.
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source Java & XML An Orixo Member
Read my weblog at http://blogs.cocoondev.org/stevenn/
stevenn at outerthought.org stevenn at apache.org
Re: Forrest & Daisy integration scenarios
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Steven Noels wrote:
...
> What do people think?
I think that we need people that write documentation, not a tool.
I'll think about it again when we have 10 doc writers sending patches
and files that we are not able to manage.
For now converting all documentation files to plain html and adding a
link from every page to the svn version would certainly make things easy
enough for most doc writers.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: [daisy] Re: Forrest & Daisy integration scenarios
Posted by Ross Gardler <rg...@apache.org>.
[Originally sent pnly to Daisy list in error, did,'t realise the
original mail had been cross posted]
Stefano Mazzocchi wrote:
> Steven Noels wrote:
>
...
>
> In perfect do-ocracy, who makes it work first, gets my vote. :-)
I'm not sure it's enough to get your vote as there is still more to do,
but I promised something tonight so here it is.
I just created a simple site demo of Daisy + Forrest. It only works in
dynamic mode at present so no published version. There are a few other
limitations (see end of this mail for known problems).
"All" it does is so how an XDoc and a document from a daisy repo can be
seemlessly integrated into a single site. More discussion below for
those of you who don't want to start up the site:
To see the site:
be sure you are running the latest SVN head of Forrest
cd FORREST_HOME/whiteboard/plugins/org.apache.forrest.plugin.input.Daisy
ant local-deploy
(this deploys the experimental daisy plugin to your local version of
Forrest, this step is needed as the plugin has not been released yet so
there is no download site for it)
cd tmp
(or wherever)
unzip the zip at
http://people.apache.org/~rgardler/testingGround/cocoonDocsDemo/daisyForrestDemo.zip
forrest run
http://localhost:8888
----
For those who don't want to start the site up I've copied the discussion
on the indes page below.page (incidentally this nicely formatted version
is generated by the Forrest Text output plugin).
Quick demo of Daisy + Forrest
Table Of Contents
=================
Daisy + Forrest = Workflow Controlled Publication of "Free For All"
Documentation
Why does this "site" exist?
Some Further Advantages of this Approach
Multiple Sites
Order From Chaos
Sorting the Wheat from the Chaff
Existing Content Integration
Third Party Content Integration
Problems
Daisy + Forrest = Workflow Controlled Publication of "Free For All"
Documentation
=================================================================================
For some background on why this was created see this mail[Link to:
http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=111591833106339&w=2]in
the Cocoon Dev Mail Archives.
This simple little site is a Forrest site built with content from two
different sources:
1. Local files that could be under SVN control (this one)
2. A remote file from the CocoonHandbook
* The original file can be found on Daisy at cocoondev
Since we are usng Forrest as the publication engine there is a very
wide range of input formts supported by this solution. See the Forrest
project[Link to: http://forrest.apache.org/]for more information.
Why does this "site" exist?
===========================
This site is a simple demonstration of the second part of the solution
described in the mail above.
The first part of that mail refers to Daisy being used to lower the
barrier to entry for Cocoon document authors. Daisy provides the first
part of the workflow system controlling the publication of edits.
The second part of that mail refers to Forrest being used to collate
the materials found in (inevitably) chaotic documentation found in the
Wiki. This site only presents a portion of the content in the wiki,
that is it presents the portion that is considered to be of suitable
quality for the released documents.
The second part talks about a staging server. This site is the staging
server. That is, install Forrest and run forrest run inside the docs
directory of the cocoon distribution and you see this site.
This means that all committers have access at all times to the current
"offical" documentation. Editing of the structure of that content is
done through tools familar to Cocoon developers, i.e. SVN and their
preferred editors. Editing of the actual content is done via the Daisy
Wiki installation. Although it is not included in this demo it would be
trivial to provide a link from the staging server back to the page to
edit the content.
The third phase is already in place. It is is the hosting of this
documentation on a web server. However, unlike the current system the
snapshots taken at release time will contain all the documentation
current for that release. No longer will the hapless user be expected
to search the multiple documention sets to try and find their answer,
nor will they have to traul through lots of false hits from incomplete
or innacurate documents.
Some Further Advantages of this Approach
========================================
Multiple Sites
--------------
The structure of the site generated using Forrest need bear no
relation to the structure of the documents in the source
repositories. This means that the final documentation can be
designed with a navigation structure that suits the reader. In fact
we can have the same content appearing in different places in
different sites, for example, we can have sites for newbies, for
technical folk, for marketing purposes, for press folk etc.
Order From Chaos
----------------
In addition to being able to have multiple site structures, this
also enables us to bring order to the chaos of "free for all"
Content Management Systems. That is, even in a CMS with a tightly
controlled publishing workflow things become chatic quite quickly.
This approach of having separate "views" on the materials enables
the CMS to be freed up to serve the content creators, rather than
the content consumers. That is the CMS can structured in a way that
is convenient to editors, for example presenting menus of items
requiring review rather than logical groupings of documents into
topic areas.
Of course, if the CMS has an adequate navigation editor, this can
be used for creating both the reader and editor views of the
repository. Forrest can be made to use those documents as either
complete site structure documents, or sub-sites to be imported into
other sites.
Sorting the Wheat from the Chaff
--------------------------------
In a "free for all" content management system it is important to
balance quality control measures against a low barrier to entry for
potential contributors. This two phased approach allows a two
points of quality control. The first is when a contribution is
accepted for publication into the "in development" documentation.
The second is when a contribution is accepted into the published
doucmentation.
The goals of this system are to make it very easy for people to
contribute to the "in development" content. Self registration is
allowed, thus anyone can edit, whilst a select number of trusted
editors are given the task of publishing edits into the CMS. These
"free" editing will result in a number of incomplete or possibly
innacurate documentation. Thus we have the second phase, which is
the Forrest site publication. This is managed by key members of the
community who decide what content will be used in the next
published set of documentation.
This allows a wide range of documents to be accepted into the CMS
whilst minimising the work involved with moving those documents
into the final documentation collection.
Existing Content Integration
----------------------------
It is recognised that there is considerable amount of documentation
in other forms, for example there are a large number of XDoc files
in Cocoons SVN, java code is annotated with tagged comments, and
the Wiki has lots of valuable content too. Since Forrest can work
with a large number of input formats it can seemlessly integrate
this content into the Cocoon documentation site.
The new plugin system in the 0.7 version of Forrest allows extra
input formats to be easily supporte. When the prposed edit link on
a page is clicked it will take the user to the relevant edit
interface for that document. Clearly it would be in the best
interests of Cocoon to bring all documentation together "under the
on roof". However this is a very big job and this mechanism can be
used to quickly integrate the existing documetnation systems whilst
gradually migrating documents to the chosen editing platform.
Third Party Content Integration
-------------------------------
Where a third party develops content that is appropriate to the
Cocoon docs it is possible to include such content (when suitably
licensed) directly within the published docs.
Problems
========
If the staging server discussed in the mail above is the local users
machine as described in this document then the user must be online to
see the complete set of documentation since the system will download
the latest version of the data when a page is requested.
This demo is based on a whiteboard plugin for Forrest to import
documents from a Daisy repository. This plugin is experimental,
discussions are ongoing with the Daisy and Forrest communities about
how best to implement it. It is pre-alpha at this stage and may not
work as expected. Known issues are:
* pdf and text generation does not work yet (simple URL rewrite
required in
Forrest skins)
* binary data does not work yet (need to add readers to Daisy plugin)
* no form of caching is implemented (make quick requesst to Daisy
Repo. to
get last update timestamp)
* menu selection does not work corectly (tweak to Forrest XSL needed)
* static publishing from Forrest does not currently work (need
locationmap in Forrest to work to enable this)
The construction of URLs for retrieving data from remote repositories
is quite cumbersome. There is a future enhancement to Forrest that will
greatly simplify this, there is also a GUI editor for content objects
under development.
_______________________________________________
daisy mailing list
daisy@lists.cocoondev.org
http://lists.cocoondev.org/mailman/listinfo/daisy
Re: Forrest & Daisy integration scenarios
Posted by Stefano Mazzocchi <st...@apache.org>.
Steven Noels wrote:
> On 12 May 2005, at 17:21, Stefano Mazzocchi wrote:
>
>> But it's also true that editing xml files in a svn repository sucks as
>> an editing tool. Using wiki (or daisy or other solutions) is much better.
>>
>> I like the notion of
>>
>> daisy -> forrest -> out
>>
>> makes very good sense.
>
>
> It does, yet there's obvious huge bits of overlap between Forrest and
> Daisy's publishing mechanism. IMO, Daisy is perfectly able to host
> Cocoon's documentation, both for editing and publishing.
>
> The bridge between Daisy and Forrest could be a Forrest exporter: i.e. a
> tool which aggregates and renders a Daisy site and converts it into a
> Forrest source xdocs + site.xml tree. This tool might find some of its
> inspiration in the work we're planning for the Daisy Books tool.
>
> If however the Cocoon documentation only consists of Daisy-managed
> content, I wonder what this exporter would buy us in the short term
> compared with a live Daisy site + custom skin, possibly wget-ed into
> static HTML for SVN storage.
>
> There's a few possible scenarios:
>
> ------------------------------
> -------| editing wiki (plain daisy) | (1)
> -------- | ------------------------------
> | repo |----|
> -------- | ---------------------------------- wget
> ---------------
> -------| wiki + custom cocoon-site skin |----------| static
> HTML | (2)
> | ----------------------------------
> ---------------
> |
> | ---------------------------------------- wget
> ---------------
> -------| publish-only lib + custom render app |----------|
> static HTML | (3)
> | ----------------------------------------
> ---------------
> |
> | -------------------- forrest ---------------
> -------| forrest exporter |-------------| static HTML | (4)
> -------------------- ---------------
>
> (1) exists already, (2) is low-hanging fruit, (3) is something we're
> working on for the next release, and (4) is possible as well, but
> requires more work.
>
> In (2), I consider the wget step to be optional for the live Cocoon
> documentation site, and only required when we want to produce static
> HTML for inclusion in the distribution, or if we want to store the
> site's content in SVN as well. Both make sense to me.
>
> In the current Daisy Forrest plugin, the interface between Forrest and
> Daisy is a rendered, jtidied Wiki page. That (a) is not a very solid
> contract IMHO, and (b) creates duplication of effort, as the site
> structure needs to be maintained in both Daisy and Forrest.
>
> Of course, if the Cocoon documentation would be a mixture of Daisy- and
> non-Daisy managed documents (like Word/OO files), we would need to come
> up with other scenarios.
>
> What do people think?
In perfect do-ocracy, who makes it work first, gets my vote. :-)
--
Stefano.