You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Mark Leicester <ma...@efurbishment.com> on 2005/05/12 15:04:48 UTC
Expert pre-defined/community post-defined? [WAS: Community health]
Hi Bertrand,
I for one have been looking at the wiki regularly, making little tweaks
here and there: nothing major, but it's a regular haunt of mine. You
can verify this at: http://wiki.apache.org/cocoon/RecentChanges
(Sébastien seems to have contributed a fair bit recently too!)
Back when Outerthought introduced the Cocoon wiki I thought it was a
cool tool (hey, not even based on Cocoon!). I liked it and introduced
it into my company too: we used it lots. We learned the good and bad of
wikis. Later, in my constant search for community enhancing tools, I
came across Drupal (a tool that is proving very successful all over the
problem space). I'm inventing as little as possible. That is, I'm
building on the work of others, at the same time as trying a slightly
different approach to that proposed already.
I think that when you suggested, "This is maybe the one tool that we're
missing: a way to add folksonomy tags to our docs to make them easier
to find", you are touching upon an important weakness of the wiki. The
wiki is great for contained ideas and snippets, but very poor at
encouraging the organisation of those snippets. With a wiki it is
difficult to evolve a taxonomy from the content (yes, there are ways).
Bertrand, I know you are a fellow user of del.icio.us and from that,
and your statement above, I think we may essentially agree on the
potential solution. A "jewel" in Drupal's "crown" is its taxonomy
system. Over the next few weeks I'll attempt to demonstrate the
benefits of this approach, coupled with folksonomy. Taxonomy is
'expert' pre-defined, folksonomy is community post-defined. I think the
latter has enormous potential to help in a community like ours. A bit
of both is probably perfect.
I think you are right, I probably have dismissed the "existing stuff" a
bit early. In that case, I pledge to keep in touch with the current
effort. I certainly value ongoing dialogue. However, I wonder out loud:
should we be putting documentation behind the barrier of committership
at all? I'm a community post-defined kind of person.
As I said above, over the next few weeks I'll attempt to demonstrate
what I imagine to be the myriad of potential benefits of the Drupal
approach.
Regards, and thanks!
Mark
On 12 May 2005, at 07:33, Bertrand Delacretaz wrote:
> Le 12 mai 05, à 06:33, Sebastien Arbogast a écrit :
>> ...FYI we have already come up with 13 very interesting ideas about a
>> potention new common documentation effort for Cocoon..
>
> Would you guys be able to at least try writing/reorganizing some docs
> in the current system [1] before inventing
> yet-another-potentially-doomed-new-tool?
>
> Excuse the tone and don't get me wrong, I'm trying to be constructive:
> building on the work of others might get you to destination earlier.
>
> My impression is that you've dismissed the existing stuff a bit early
> without really trying it. Writing/reorganizing docs is really easy
> with the 2.2 docs system, and if non-commitership is a problem there's
> certainly a way to solve it.
>
> Let us know if you have any questions or specific problems about how
> to write docs for the 2.2 trunk.
>
> -Bertrand
>
> [1] http://wiki.apache.org/cocoon/22NewDocumentsGeneration
Re: Expert pre-defined/community post-defined? [WAS: Community health]
Posted by Sebastien Arbogast <se...@gmail.com>.
> http://www.mail-archive.com/dev@cocoon.apache.org/msg05839.html
> http://marc.theaimsgroup.com/?t=110568730000003&r=1&w=2
> http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=106691291922337&w=2
Thanks for the link, we gonna use it as an idea-source.
> There is very little that you guys said that hasn't been said in the
> past, that's why people are so <yawn> about it.
That's not because it has already been said or mentioned that it's
always useless to precise things. Those kind of things have to be
alive and it's precisely to make those good ideas more persistent (and
avoir resaying the same things several times) that we are working on a
brainstorming forum on PlanetCocoon.
> And the first one being guilty of blah blah without acting is *myself*.
>
> You'll find all the ideas you want from those threads. We know what we
> need inside out, we just need to find a way to make it happen and stop
> talking about it.
You're totally right. I got the message and be sure we are working on it.
--
Sebastien ARBOGAST
Re: Expert pre-defined/community post-defined? [WAS: Community health]
Posted by Sylvain Wallez <sy...@apache.org>.
Sebastien Arbogast wrote:
>>Such management tools should allow people that have the responsibility
>>to validate and publish content on the website to quickly grasp the job
>>they have to do. For example, I may want to have a quick look at all
>>changed documents that have the "forms" "flowscript" or "sitemap" tags,
>>without having to scroll through all the tags. Or also notification
>>emails or RSS feeds to track changes to such tags.
>>
>>What I'm seeking for is tools that make writing docs really easy. If the
>>process to perform a task for which you don't have a high motivation is
>>too heavy, then you simply don't do that task. If the tools make this
>>easy and notify you (in whatever form) of what you have or should do,
>>then there's a higher chance that you will do it.
>>
>>Well, I guess I'm describing something named... is it CMS? ;-P
>>
>>
>
>Waouh Sylvain this is just great. Mark I hope you're taking notes
>because he is quite prolific ;-P
>
>
Hehe. After lazy consensus, you discover that things often don't happen
not because people are against it, but because they're lazy. Give them
tools that lower the amount of energy they need to spend and the job has
a higher change of being done ;-)
I sometimes do presentations about how opensource works. And something
that really amazes people is all the tools and processes that OSS
communities have set up over time to ease their job, which the have a
lot to learn from. If we have CVS (or SVN), Ant build, mail archives,
unit tests and all that stuff, it's not because we are some strict and
rational IT professionnals, but because without these tools, the ratio
of time spent to really doing things is to low. Tools are necessary for
OSS communities to survive.
>I see at least 5 new ideas in this new thread, ideas we have to
>integrate in brainstorming forum. This is just great, this is exactly
>the kind of feedback we need.
>
>
Hehe, your rant has shaken some minds, and started this constructive
discussion. Sometimes a little rant is good to awaken people. But one
needs to find the correct amount of rant so that awaken people start a
constructive discussion and do not start to collectively shoot the
messenger ;-)
Cheers,
Sylvain
--
Sylvain Wallez Anyware Technologies
http://apache.org/~sylvain http://anyware-tech.com
Apache Software Foundation Member Research & Technology Director
Re: Expert pre-defined/community post-defined? [WAS: Community health]
Posted by Stefano Mazzocchi <st...@apache.org>.
Sebastien Arbogast wrote:
>>Such management tools should allow people that have the responsibility
>>to validate and publish content on the website to quickly grasp the job
>>they have to do. For example, I may want to have a quick look at all
>>changed documents that have the "forms" "flowscript" or "sitemap" tags,
>>without having to scroll through all the tags. Or also notification
>>emails or RSS feeds to track changes to such tags.
>>
>>What I'm seeking for is tools that make writing docs really easy. If the
>>process to perform a task for which you don't have a high motivation is
>>too heavy, then you simply don't do that task. If the tools make this
>>easy and notify you (in whatever form) of what you have or should do,
>>then there's a higher chance that you will do it.
>>
>>Well, I guess I'm describing something named... is it CMS? ;-P
>
>
> Waouh Sylvain this is just great. Mark I hope you're taking notes
> because he is quite prolific ;-P
> I see at least 5 new ideas in this new thread, ideas we have to
> integrate in brainstorming forum. This is just great, this is exactly
> the kind of feedback we need.
Sebastien, read these threads:
http://www.mail-archive.com/dev@cocoon.apache.org/msg05839.html
http://marc.theaimsgroup.com/?t=110568730000003&r=1&w=2
http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=106691291922337&w=2
There is very little that you guys said that hasn't been said in the
past, that's why people are so <yawn> about it.
And the first one being guilty of blah blah without acting is *myself*.
You'll find all the ideas you want from those threads. We know what we
need inside out, we just need to find a way to make it happen and stop
talking about it.
--
Stefano.
Re: Expert pre-defined/community post-defined? [WAS: Community health]
Posted by Sebastien Arbogast <se...@gmail.com>.
> Such management tools should allow people that have the responsibility
> to validate and publish content on the website to quickly grasp the job
> they have to do. For example, I may want to have a quick look at all
> changed documents that have the "forms" "flowscript" or "sitemap" tags,
> without having to scroll through all the tags. Or also notification
> emails or RSS feeds to track changes to such tags.
>
> What I'm seeking for is tools that make writing docs really easy. If the
> process to perform a task for which you don't have a high motivation is
> too heavy, then you simply don't do that task. If the tools make this
> easy and notify you (in whatever form) of what you have or should do,
> then there's a higher chance that you will do it.
>
> Well, I guess I'm describing something named... is it CMS? ;-P
Waouh Sylvain this is just great. Mark I hope you're taking notes
because he is quite prolific ;-P
I see at least 5 new ideas in this new thread, ideas we have to
integrate in brainstorming forum. This is just great, this is exactly
the kind of feedback we need.
--
Sebastien ARBOGAST
Re: Expert pre-defined/community post-defined? [WAS: Community health]
Posted by Sylvain Wallez <sy...@apache.org>.
Steven Noels wrote:
> On 12 May 2005, at 15:56, Sylvain Wallez wrote:
>
>> - inline WYSIWYS (what you see is what you structure, i.e. htmlarea
>> or something similar, but no wiki or XML syntax)
>
>
> Check.
>
>> - version management, so that validated content can be published on
>> cocoon.apache.org while newer versions are being written
>
>
> Check (support for branches in 1.3M1)
>
>> - tagging, to produce the classification of docs and ease navigation
>
>
> There's support for multi-valued fields coming up in the next release.
> You can embed queries in the navigation tree since 1.0.
>
>> - some management tools allowing to quickly see what has changed and
>> needs to be validated.
>
>
> Don't fully understand, though I guess "notification mails" and
> "recent changes" and "query language" should cover this adequately.
Such management tools should allow people that have the responsibility
to validate and publish content on the website to quickly grasp the job
they have to do. For example, I may want to have a quick look at all
changed documents that have the "forms" "flowscript" or "sitemap" tags,
without having to scroll through all the tags. Or also notification
emails or RSS feeds to track changes to such tags.
What I'm seeking for is tools that make writing docs really easy. If the
process to perform a task for which you don't have a high motivation is
too heavy, then you simply don't do that task. If the tools make this
easy and notify you (in whatever form) of what you have or should do,
then there's a higher chance that you will do it.
Well, I guess I'm describing something named... is it CMS? ;-P
Sylvain
--
Sylvain Wallez Anyware Technologies
http://apache.org/~sylvain http://anyware-tech.com
Apache Software Foundation Member Research & Technology Director
Re: Expert pre-defined/community post-defined? [WAS: Community health]
Posted by Ross Gardler <rg...@apache.org>.
Steven Noels wrote:
> On 12 May 2005, at 16:36, Upayavira wrote:
...
> I was just chatting with Sylvain about this. We don't have time to
> create an xdocs export for Daisy, but if all goes well, we'll be doing
> Daisy Books (aggregation and book-like publishing) over summer. Those
> would target XSL-FO and HTML as rendition formats. Maybe someone can
> track this to see how easy it would be to do an xdocs exporter as well.
As I said in an overlapping mail, Forrest has an alpha quality Daisy
plugin and since Cocoon use Forrest problem solved (incidentally this
means that documents uploaded in Open Office Impress or Word and MS
Office Powerpoint, word or excel are also included, together with other
source formats such as wiki, docbook, POD, even plain old text :-))
DITA is in the pipeline, even Drupal imports is a possibility if enough
need arose.
> Of course, since the Wiki already supports branching, it already
> supports most software documentation needs IMHO. But one could always
> create a barebones skin and run wget over it to produce frozen, SVN-able
> static HTML files.
Forrest can be run either dynamically, therefore giving a realtime view
of the repositories or to create a static site in order to put snapshots
into SVN and releases. These snapshots can be in any output format
supported by Forrest (XDoc, XHTML, PDF etc.)
(note today I started a thread over on the daisy dev lists about using
Forrest to implement their "publish only" goal on their roadmap,
interested folk should contribute to that thread).
Ross
Re: Expert pre-defined/community post-defined? [WAS: Community health]
Posted by Steven Noels <st...@outerthought.org>.
On 12 May 2005, at 16:36, Upayavira wrote:
> To validate whether a document should be published, i.e. to review it,
> which involves clearly seeing what the author changed.
Check.
> A document has been updated:
>
> http://cocoondev.org/daisydocs-1_3/37
>
> Document ID: 37
> Branch: daisydocs-1_3
> Language: en
> Name: User Management (unchanged)
> Document Type: Simple Document (unchanged)
> Updated on: 5/9/05 8:09:07 AM
> Updated by: Bruno Dumon
>
> A new version has been created, state: publish
>
> Parts
> =====
> Content
> -------
> This part has been updated.
> Mime type: text/xml (unchanged)
> Size: 5936 bytes (previous version: 5592 bytes)
> Content diff:
> <html>
> <body>
>
> <p>All operations done on the Daisy Repository Server are done as
> a certain user
> --- acting in a certain role. For this purpose, the Repository Server
> has a User
> --- Management module to define the users and the roles. An
> Authenticator component
> --- is responsible for the authentication.</p>
> +++ acting in a certain role. For this purpose, the Repository Server
> has a user
> +++ management module to define the users and the roles. The
> authentication of the
> +++ users is done by a separate component, allowing to plug in custom
> authentication
> +++ techniques.</p>
>> Again, I'm not pushing, nor offering to run it on our own hardware.
>> Not that I don't want to administer or help out. Just that I don't
>> want this to be a solo job.
>
> ASF infra are just getting solaris zones up and running. Shouldn't be
> long before we can have one of those for ourselves. Also, there is a
> new discussion about site publishing ASF-wide that this could fit into
> - whatever we chose to base our system on daisy, drupal, zope, or xml
> files.
I was just chatting with Sylvain about this. We don't have time to
create an xdocs export for Daisy, but if all goes well, we'll be doing
Daisy Books (aggregation and book-like publishing) over summer. Those
would target XSL-FO and HTML as rendition formats. Maybe someone can
track this to see how easy it would be to do an xdocs exporter as well.
Of course, since the Wiki already supports branching, it already
supports most software documentation needs IMHO. But one could always
create a barebones skin and run wget over it to produce frozen,
SVN-able static HTML files.
</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: Expert pre-defined/community post-defined? [WAS: Community health]
Posted by Upayavira <uv...@odoko.co.uk>.
Steven Noels wrote:
> On 12 May 2005, at 15:56, Sylvain Wallez wrote:
>
>> - inline WYSIWYS (what you see is what you structure, i.e. htmlarea or
>> something similar, but no wiki or XML syntax)
>
>
> Check.
>
>> - version management, so that validated content can be published on
>> cocoon.apache.org while newer versions are being written
>
>
> Check (support for branches in 1.3M1)
>
>> - tagging, to produce the classification of docs and ease navigation
>
> There's support for multi-valued fields coming up in the next release.
> You can embed queries in the navigation tree since 1.0.
>
>> - some management tools allowing to quickly see what has changed and
>> needs to be validated.
>
> Don't fully understand, though I guess "notification mails" and "recent
> changes" and "query language" should cover this adequately.
To validate whether a document should be published, i.e. to review it,
which involves clearly seeing what the author changed.
> Again, I'm not pushing, nor offering to run it on our own hardware. Not
> that I don't want to administer or help out. Just that I don't want this
> to be a solo job.
ASF infra are just getting solaris zones up and running. Shouldn't be
long before we can have one of those for ourselves. Also, there is a new
discussion about site publishing ASF-wide that this could fit into -
whatever we chose to base our system on daisy, drupal, zope, or xml files.
Regards, Upayavira
Re: Expert pre-defined/community post-defined? [WAS: Community health]
Posted by Steven Noels <st...@outerthought.org>.
On 12 May 2005, at 15:56, Sylvain Wallez wrote:
> - inline WYSIWYS (what you see is what you structure, i.e. htmlarea or
> something similar, but no wiki or XML syntax)
Check.
> - version management, so that validated content can be published on
> cocoon.apache.org while newer versions are being written
Check (support for branches in 1.3M1)
> - tagging, to produce the classification of docs and ease navigation
There's support for multi-valued fields coming up in the next release.
You can embed queries in the navigation tree since 1.0.
> - some management tools allowing to quickly see what has changed and
> needs to be validated.
Don't fully understand, though I guess "notification mails" and "recent
changes" and "query language" should cover this adequately.
Again, I'm not pushing, nor offering to run it on our own hardware. Not
that I don't want to administer or help out. Just that I don't want
this to be a solo job.
</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: Expert pre-defined/community post-defined? [WAS: Community health]
Posted by Sylvain Wallez <sy...@apache.org>.
Mark Leicester wrote:
> Hi Bertrand,
>
> I for one have been looking at the wiki regularly, making little
> tweaks here and there: nothing major, but it's a regular haunt of
> mine. You can verify this at:
> http://wiki.apache.org/cocoon/RecentChanges (Sébastien seems to have
> contributed a fair bit recently too!)
>
> Back when Outerthought introduced the Cocoon wiki I thought it was a
> cool tool (hey, not even based on Cocoon!). I liked it and introduced
> it into my company too: we used it lots. We learned the good and bad
> of wikis. Later, in my constant search for community enhancing tools,
> I came across Drupal (a tool that is proving very successful all over
> the problem space). I'm inventing as little as possible. That is, I'm
> building on the work of others, at the same time as trying a slightly
> different approach to that proposed already.
>
> I think that when you suggested, "This is maybe the one tool that
> we're missing: a way to add folksonomy tags to our docs to make them
> easier to find", you are touching upon an important weakness of the
> wiki. The wiki is great for contained ideas and snippets, but very
> poor at encouraging the organisation of those snippets. With a wiki it
> is difficult to evolve a taxonomy from the content (yes, there are
> ways). Bertrand, I know you are a fellow user of del.icio.us and from
> that, and your statement above, I think we may essentially agree on
> the potential solution. A "jewel" in Drupal's "crown" is its taxonomy
> system. Over the next few weeks I'll attempt to demonstrate the
> benefits of this approach, coupled with folksonomy. Taxonomy is
> 'expert' pre-defined, folksonomy is community post-defined. I think
> the latter has enormous potential to help in a community like ours. A
> bit of both is probably perfect.
>
> I think you are right, I probably have dismissed the "existing stuff"
> a bit early. In that case, I pledge to keep in touch with the current
> effort. I certainly value ongoing dialogue. However, I wonder out
> loud: should we be putting documentation behind the barrier of
> committership at all? I'm a community post-defined kind of person.
>
> As I said above, over the next few weeks I'll attempt to demonstrate
> what I imagine to be the myriad of potential benefits of the Drupal
> approach.
Please go on in this folksonomy approach. It definitely looks interesting.
Documentation of any large system is twofold:
- the reference documentation, that should come from developers, because
it comes from the code
- the usage documentation, that should come from users, because it comes
from ways people have found to solve their problems.
Cocoon is probably special in that it's more a toolbox than a
well-defined product, and its developers are also its first and most
intensive users. But they are special users that don't really need the
docs as they've written the code. Hence IMO the fewer itches to scratch
to provide better docs to regular users. Also, we write new features to
solve our everyday problems, whereas non-devs have to use what we
provide them.
This has led to the status of our docs, where lots of users have
contributed lots of good wiki pages, but where few devs care to organize
this valuable content (and I easily admit that I'm not one of them).
So Cocoon authoring should be wide open to users, under of course the
control of devs that should proof-read and validate the content, using a
tool that easily allows import into the cocoon.apache.org website
(that's not the case of the wiki). Classification will come by itself if
docs can be tagged, as although it's easy to write mistakes in the
content if you don't know the code well, it's more difficult to attach
an invalid tag to that content (unless you do it on purpose of course).
I don't know if that tool should be Drupal or Daisy, but the important
requirements from my POV are:
- inline WYSIWYS (what you see is what you structure, i.e. htmlarea or
something similar, but no wiki or XML syntax)
- version management, so that validated content can be published on
cocoon.apache.org while newer versions are being written
- tagging, to produce the classification of docs and ease navigation
- some management tools allowing to quickly see what has changed and
needs to be validated.
Maybe I'm just restating evidences, but that's why would make _me_ more
inclined a writing docs.
My 0.02 euros,
Sylvain
--
Sylvain Wallez Anyware Technologies
http://apache.org/~sylvain http://anyware-tech.com
Apache Software Foundation Member Research & Technology Director
Re: Expert pre-defined/community post-defined? [WAS: Community health]
Posted by Bertrand Delacretaz <bd...@apache.org>.
Le 12 mai 05, à 15:04, Mark Leicester a écrit :
> ...As I said above, over the next few weeks I'll attempt to
> demonstrate what I imagine to be the myriad of potential benefits of
> the Drupal approach...
Sounds interesting - I'll stay tuned!
-Bertrand
Document publishing worklow (was Re: Expert pre-defined/community
post-defined?)
Posted by Ross Gardler <rg...@apache.org>.
Stefano Mazzocchi wrote:
> I like the notion of
>
> daisy -> forrest -> out
>
> makes very good sense.
>
> Now we just need to find a way to automate a little that workflow, but
> without introducing security vulnerabilities.
How about this (bullet summaries followed by textual description.
Daisy as editing environment.
- anyone can edit
- people are given quick "committership" here
- change mails are sent out by Daisy for docs committer review
- docs committers review changes and publish to the daisy repo
Forrest as publishing tool
- cocoon committers manage a
- brings together XDocs, wiki docs, Daisy docs etc.
- publish to (or dynamically host on) a staging server
Offical Docs site
- live Apache site is pulled from staging server
Daisy as editing environment
----------------------------
Daisy-Wiki provides WYSIWYN (What you see is what you *need*), wysiwyg
editing, version control, user admin, semi-structured docs management,
email notification of edits, comment system and much much more.
Since the Dasy repository is completely separate from the code base
committership to this repository can be more freely given. The job of
the docs committers (editors?) is to ensure that content is of a
reasonable quality and is appropriate content (i.e. keep out spam).
It is *not* the job of these people to ensure technical accuracy of
content, although it is hoped that they will do there best here too.
This gives us the first phase of our approval process:
- any user edits docs in the Daisy Wiki
- mail sent to either the docs list
- edit is approved/rejected as appropriate
- mail is sent out to docs list
When a new page is published to the Daisy wiki then a dev is tasked with
reviewing that page for incusion in the docs content object (discussed
further in the next section>
Forrest as publishing tool
--------------------------
A separate Forrest site is used to create the official docs for Cocoon.
The structure of this site is managed by the devs and is maintained in
SVN. Since it is the devs who manage this site structure they have final
control over which of the Daisy published docs are considered good
enough for the offcicial Cocoon stamp of approval. In other words, this
is the point at which the technical accuracy of the docs is maintained.
The final Cocoon documentation can include content from many sources.
For example there are the existing SVN docs, the wiki docs and other
docs generated by other sites. Cocoon commiters manage a docs "content
object" that bring together all these different sources and attached
appropriate credits for third party docs that are given the official
"Cocoon seal of approval".
It is worth noting that the Burrokeet (http://www.burrokeet.org )
project is developing a GUI interface for managing such content objects.
This content object is published to a staging server via SVN and thus
devs are notified of docs changes automatically and a record of the
"official" documentation is kept in SVN (some people felt this was a
requriement).
This gives us the second phase of our approval process since devs are
monitoring the SVN commit logs anyway.
Offical Docs site
-----------------
The official documentation is pulled from the staging repository using
rsync or similar by a process triggered by the devs at an appropriate
time and managed by a docs release process.
What needs to be done?
======================
The daisy wiki needs to be hosted somewhere.
The Daisy plugin for Forrest needs to be completed (I'm volunteering for
this)
The last stage (syncing to the public site) needs to be fleshed out and
a release process needs to be written to decide how and when this
syncing is done.
????
Ross
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.
Forrest & Daisy integration scenarios
Posted by Steven Noels <st...@outerthought.org>.
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: Expert pre-defined/community post-defined? [WAS: Community health]
Posted by Stefano Mazzocchi <st...@apache.org>.
Mark Leicester wrote:
> I think you are right, I probably have dismissed the "existing stuff" a
> bit early. In that case, I pledge to keep in touch with the current
> effort. I certainly value ongoing dialogue. However, I wonder out loud:
> should we be putting documentation behind the barrier of committership
> at all? I'm a community post-defined kind of person.
Finally some real issue.
Yes, I agree with you: code commits and docs commits are separate
things. The HTTPD project already contains this notion of separate
committership. I would be in *TOTAL* favor of giving docs committership
to a separate SVN module a lot faster.
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.
Now we just need to find a way to automate a little that workflow, but
without introducing security vulnerabilities.
> As I said above, over the next few weeks I'll attempt to demonstrate
> what I imagine to be the myriad of potential benefits of the Drupal
> approach.
Great.
--
Stefano.