You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by Brian Topping <to...@digidemic.com> on 2002/05/29 13:15:40 UTC
Intro / etc.
Hi All,
My name is Brian, I've been looking around at the mail archives and progress of Forrest, it's great! I'm just introducing myself, I guess. I'm really into CMS, it's something I'm doing for my main line of work.
I'm not sure how many of you have heard of Xopus, but it's a very cool (and very lightweight) browser plugin that allows inline editing of XML documents. See http://www.q42.nl/products/xopus/ and try the demo to actually understand what I am talking about. I don't have any connection with these guys, I just think their technology rocks the house.
I saw the CMS thread that happened a couple of weeks back, and I don't want to flog a dead horse, but I would like to throw in a prop for doing a CMS within Forrest sooner than later. Here's why:
I'm starting to believe that ad-hoc user-generated documentation may be what gets people to write docs. By this, I mean truly living documents that users can edit. Check out the sections of http://mysql.org/doc/ for an example. At the end of each section, users can add comments that elaborate the documentation and leave "popcorn" for the maintainers to update the site. Forrest is most successful so far as a documentation system, and documentation is what seems to be lacking in the world. So it seems to make sense to really kick some butt with the handling of documentation. Gracefully integrating user changes, as they have them, seems to be something that would make a lot of sense.
To illustrate, a couple of examples:
An example of how it *shouldn't* be: Over the last week or so have contributed some diffs that would help people avoid some build and install issues I hit with a couple of random projects. They haven't been merged yet, so my attention deficit disorder has me wondering whether I should make more diffs, since the instant gratification that I can get somewhere else isn't there.
My idea of how it should be, with Xopus: I see a problem that I want to fix on a page. I log into the site, and since I'm in Mozilla, I hit F7 to edit the text. Xopus comes in to let me edit the text -- inline. When I am finished, Xopus pushes the changes to the server. My changes are *not* immediately put on the site, but are queued. The queue is managed by Scarab, logged as a documentation bug with a patch, and both myself and the maintainer are notified in standard Scarab fashion. The next time the maintainer logs in, a viewer shows the changes and allows them to accept or reject the changes. If they are accepted, they are pushed to CVS. Either way, I am notified of the accept/reject status of my work, again via Scarab. There is no room for loss of my work, and I can track the status and who is responsible for reviewing my changes.
The reason I am yammering about this is because all the parts are there (Wyona for CMS, Xopus for XML editor, Scarab for issue tracking, just add glue), and adding this to Forrest would leverage it to any project that used it. It would add a very fast feedback cycle to people that wanted to add to the documentation, which would increase participation. Since docs are a weak point of all projects, if it was successful at increasing participation on them, nobody would think of doing a project without it.
The ugly stick with these kind of systems is that they are another database system that needs to be maintained, but if everything could be managed through Scarab, the extra cost is really back to zero. And if it gets people to contribute to documentation, how much is *that* worth?!? :-)
It might be worth thinking about!
-b
Re: Intro / etc.
Posted by Nicola Ken Barozzi <ni...@apache.org>.
From: "Diana Shannon" <te...@mac.com>
>
> On Wednesday, May 29, 2002, at 08:52 AM, Nicola Ken Barozzi wrote:
>
> > For now I think that implementing browser editing, maybe with fallback
> > to a
> > form system, that dialogues with Scarab would be a very important step.
>
> I assume we could implement this now with static sites with forms? For
> example, my community stuff anticipates comments (I called them
> revisions). Right now, they were designed to be submitted as patches via
> Bugzilla interface, dropped into directories by committers. Any reason
> why we can't automate the Bugzilla submission via a separate form (with
> comments directly added), at least for now?
Yes, this is *exactly* the idea.
Bugzilla itself is a form based system, so it should not be hard to do, we
can basically duplicate the bug entry form of bugzilla already tailored to
our needs and have the preset values as hidden tags...
the only thing is that it needs you to login, but for now we can ask the
user to do that first (with a form for login).
Any takers?
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
[update] moved documentation resources dirs in /resources
Posted by Nicola Ken Barozzi <ni...@apache.org>.
(taken from CVS commit message, in case you're not on xml-forrest-cvs)
Moved documentation generation resources to ./src/resources, so that
src/documentation contains the project documentation and not the
documentation system. which is Forrest itself.
This makes it easier to provide the service for other projects, which
basically
need to have a src/documentation dir akin to Forrest's.
Removed also the scarab-site skin that was implemented badly (it takes
less to make it from scratch using the style at tigris.org) and the
cocoon-printer skin that was crap (supplanted anyway by the "basic" skin).
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: Intro / etc.
Posted by Diana Shannon <te...@mac.com>.
On Wednesday, May 29, 2002, at 08:52 AM, Nicola Ken Barozzi wrote:
> For now I think that implementing browser editing, maybe with fallback
> to a
> form system, that dialogues with Scarab would be a very important step.
I assume we could implement this now with static sites with forms? For
example, my community stuff anticipates comments (I called them
revisions). Right now, they were designed to be submitted as patches via
Bugzilla interface, dropped into directories by committers. Any reason
why we can't automate the Bugzilla submission via a separate form (with
comments directly added), at least for now?
Diana
Re: Intro / etc.
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Hi Brian,
what you say makes perfect sense to me.
The idea I had about it, and I think others had too, was something between
these lines, and I thank you for having made it so clear :-)
I wasn't aware that Xopus could be used *seamlessly* with Scarab, and this
is very good news indeed.
In fact we have resorted to using Bugzilla right now, and what you explain
is the next correct step.
What I envision is a system that can different methods of access and of
complexity.
The first level is certainly what you propose, and it would be really great
if you could do it. It's for normal users and comments, and pointly
contributions.
The second level is a JNPL launchable Java App that can edit the document,
create others, and use a store underneath (like CVS now) directly, and help
for basic back-end document management.
It's the documenter's tool, and has the positive point of not having to be
hosted by a server, which is a good thing for us, given the resources we
have now and for the near future.
The third level is that of a technitian, currently CVS, with direct access
to the repository, and a more complex management console.
As for the implementation of the second level, I have an app that could be
used for it, and will release it opensource on krysalis as soon as possible.
For now I think that implementing browser editing, maybe with fallback to a
form system, that dialogues with Scarab would be a very important step.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
----- Original Message -----
From: Brian Topping
To: forrest-dev@xml.apache.org
Sent: Wednesday, May 29, 2002 1:15 PM
Subject: Intro / etc.
Hi All,
My name is Brian, I've been looking around at the mail archives and progress
of Forrest, it's great! I'm just introducing myself, I guess. I'm really
into CMS, it's something I'm doing for my main line of work.
I'm not sure how many of you have heard of Xopus, but it's a very cool (and
very lightweight) browser plugin that allows inline editing of XML
documents. See http://www.q42.nl/products/xopus/ and try the demo to
actually understand what I am talking about. I don't have any connection
with these guys, I just think their technology rocks the house.
I saw the CMS thread that happened a couple of weeks back, and I don't want
to flog a dead horse, but I would like to throw in a prop for doing a CMS
within Forrest sooner than later. Here's why:
I'm starting to believe that ad-hoc user-generated documentation may be what
gets people to write docs. By this, I mean truly living documents that
users can edit. Check out the sections of http://mysql.org/doc/ for an
example. At the end of each section, users can add comments that elaborate
the documentation and leave "popcorn" for the maintainers to update the
site. Forrest is most successful so far as a documentation system, and
documentation is what seems to be lacking in the world. So it seems to make
sense to really kick some butt with the handling of documentation.
Gracefully integrating user changes, as they have them, seems to be
something that would make a lot of sense.
To illustrate, a couple of examples:
An example of how it *shouldn't* be: Over the last week or so have
contributed some diffs that would help people avoid some build and install
issues I hit with a couple of random projects. They haven't been merged
yet, so my attention deficit disorder has me wondering whether I should make
more diffs, since the instant gratification that I can get somewhere else
isn't there.
My idea of how it should be, with Xopus: I see a problem that I want to fix
on a page. I log into the site, and since I'm in Mozilla, I hit F7 to edit
the text. Xopus comes in to let me edit the text -- inline. When I am
finished, Xopus pushes the changes to the server. My changes are *not*
immediately put on the site, but are queued. The queue is managed by
Scarab, logged as a documentation bug with a patch, and both myself and the
maintainer are notified in standard Scarab fashion. The next time the
maintainer logs in, a viewer shows the changes and allows them to accept or
reject the changes. If they are accepted, they are pushed to CVS. Either
way, I am notified of the accept/reject status of my work, again via Scarab.
There is no room for loss of my work, and I can track the status and who is
responsible for reviewing my changes.
The reason I am yammering about this is because all the parts are there
(Wyona for CMS, Xopus for XML editor, Scarab for issue tracking, just add
glue), and adding this to Forrest would leverage it to any project that used
it. It would add a very fast feedback cycle to people that wanted to add to
the documentation, which would increase participation. Since docs are a
weak point of all projects, if it was successful at increasing participation
on them, nobody would think of doing a project without it.
The ugly stick with these kind of systems is that they are another database
system that needs to be maintained, but if everything could be managed
through Scarab, the extra cost is really back to zero. And if it gets
people to contribute to documentation, how much is *that* worth?!? :-)
It might be worth thinking about!
-b