You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Mikhail Fedotov <mi...@kittown.com> on 2002/06/27 08:34:39 UTC
docs & misc
Hi!
> After just a few hours of poking around I have decided
> that it will be much simpler for me to simply hand-code
> a whole hat-full of servlets than to try and pull any
> meaning out of Cocoon and it's documentation.
Two things to mention:
1. I've been talking here about documentation in form of
dictionary, where is no structure and long docs, just
complete descriptions of components and their parameters;
it is the quick way to produce complete components
documentation that helps in creation of more complex
documentation. If someone will become interested in
lowering the difficulty of writiting docs (that I've been
talking about), and not just writing another docs page
(that I've been told to do as an response), he could arise
that topic again.
2. About the current docs. They aren't _that_ bad, there is
much of information. But it looks more like an student
work, i.e. it gives impression of work made, but not
optimized for easy understanding and using. Here is one
good model usable in too much contexts to mention, and it
is also good in writing docs:
***
S.C.O.R.E.
Symptoms/State - that problems look like, current state
Causes - that are causes of those problems (in the past?)
Outcome - that state we want to reach after changes
Resources - that we can use to do that
Effects - that is benefit of a new state and that are
drawbacks.
***
For example, at the most general level, SoC pattern and
dependencies problem:
***
Symptoms - complex webapp, many documents, big hierarchy,
difficulties with all this; some paragraphs about it.
Causes - hierachy isn't structured, components dependence
is out-of-control, bad code reuse, too much amount of
everything, etc; some paragraphs about it.
Outcome - doing things in a more structured way; some
paragraphs about it.
Resources - use of SoC pattern with Cocoon2 as a tool,
transforming the hierarchy into tree with no dependency
between branches; some paragraphs about it.
Effects - minimum update/modification time compared to
starting state, but requirement to invest additional time
in study of tools, at least; some paragraphs about it.
***
Well, this application of S.C.O.R.E. is quick and dirty,
I've just tried to do it fast. But this model really do
worth in terms of understanding. Positive side of effects
is that drive us to get outcome, and negative side it that
could made us to change our plans. Outcome by itself
doesn't mean anything.
It could be used to refactor current documentation. Even
matchers can be put into SCORE - that we had and weren't
satisfied with (well, we had servlets-like url mapping),
that state we want (maybe it's current cocoon url mapping
mechanism? well, I don't think it's ideal, but that's me),
that is preventing us from moving (don't know, except that
there were no matchers code before it was written), that
resources we have to help us move (all possible ways to map
an url into processing code and ways to implement them),
and that effects we'll have after we reach our state.
Effects are benefits and disadvantages of using matchers.
For me, it is a bit too low-level instrument, but again,
that's me.
This model requires thinking abilities, but pays off. The
best of all, it helps to detect defect ideas. And it is
reasy to use.
> complete lack of consistency between different
> components (i.e. functional code, non-functional
> examples, unbuildable documentation and a website
> that doesn't match up with any single
> released version of the project).
That's a very familiar pain. But I don't think there is an
immediate solution for it in open source development.
Mikhail
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [USER POLL] New cocoon-docs mailing list?
Posted by Liam Morley <lm...@gdc.wpi.edu>.
I definitely see a need to focus heavily on documentation, and if such a
list would have that result, I'm certainly all for it.
Liam Morley
Nicola Ken Barozzi wrote:
> The Cocoon documentation project has started with the great help of
> Diana Shannon, and is gaining good momentum and interest :-)
>
> In case you don't already know, on the dev list we have decided that a
> cocoon-docs mailing list could help this subproject and facilitate
> contributors.
>
> We are *seriously* committed to Cocoon, and to the *best*
> documentation it can have.
>
> *******************************************************
>
> Users, do you think it's time for a cocoon-docs list?
>
> *******************************************************
>
>
---------------------------------------------------------------------
Please check that your question has not already been answered in the
FAQ before posting. <http://xml.apache.org/cocoon/faq/index.html>
To unsubscribe, e-mail: <co...@xml.apache.org>
For additional commands, e-mail: <co...@xml.apache.org>
Re: web-app tutorial
Posted by "Andrew C. Oliver" <ac...@apache.org>.
Thats what XML-Form + actions does. Take a closer look at the the
how-to. I was able to cut and
paste that code pretty quckly. I've written a hello-XML-form example
but I haven't had time to formalize it.
-Andy
>This outlines the kind of thing I'd like to be able to do.
>
>--
>public class GuessGame {
> private int target, guess, steps = 0;
> private boolean hasGuessed;
> private String action; // value of form submit
>
> public GuessGame() {
> this.target = (int)Math.random(100);
> }
>
> public void setAction(String action) {
> this.action = action;
> }
>
> public String getMode() {
> if(action.equals("Cancel")) return "cancel";
> else if(haveGuessed) {
> return (guess == target) ? "final" : "guessing";
> } else return "initial";
> }
>
> public int getGuess() {
> return guess;
> }
>
> public void setGuess(int guess) {
> this.guess = guess;
> haveGuessed = true;
> ++steps;
> }
>}
>--
><%-- Have some way to map requests to bean logic.
> With the bean data available to the stylesheet.
> --%>
><jsp:useBean name="game" class="GuessGame" scope="session"/>
><jsp:setProperty id="game" name="*"/>
>
>--
><xsl:stylesheet>
>
> <xsl:template match="game" mode="initial">
> Hit Next to begin the game or Quit to close.
> <form>
> <input type="submit" name="action" value="Next"/>
> <input type="submit" name="action" value="Quit"/>
> </form>
> </xsl:template>
>
> <xsl:template match="game" mode="guessing">
> Sorry! <xsl:value-of select="@guess"/> was
> <xsl:choose>
> <xsl:when test="@guess > @target">
> too high.
> </xsl:when>
> <xsl:otherwise>
> too low.
> </xsl:otherwise>
> </xsl:choose>
>
> Guess again.
>
> <form>
> <input type="text" name="guess" value="{@guess}"/>
> <input type="submit" name="action" value="Next"/>
> <input type="submit" name="action" value="Quit"/>
> </form>
> </xsl:template>
>
> <xsl:template match="game" mode="final">
> You got it in <xsl:value-of select="@steps"/> steps!
> <form>
> <input type="submit" name="action" value="Quit"/>
> </form>
> </xsl:template>
>
> <xsl:template match="game" mode="quit">
> Thanks for playing.
> </xsl:template>
></xsl:stylesheet>
>--
>
>Anyways, I'd like to do something like that, but what components go in the
>middle between beans and xsl is a mystery....
>
>
>
>---------------------------------------------------------------------
>Please check that your question has not already been answered in the
>FAQ before posting. <http://xml.apache.org/cocoon/faq/index.html>
>
>To unsubscribe, e-mail: <co...@xml.apache.org>
>For additional commands, e-mail: <co...@xml.apache.org>
>
>
>
>
---------------------------------------------------------------------
Please check that your question has not already been answered in the
FAQ before posting. <http://xml.apache.org/cocoon/faq/index.html>
To unsubscribe, e-mail: <co...@xml.apache.org>
For additional commands, e-mail: <co...@xml.apache.org>
web-app tutorial
Posted by Guy McArthur <gu...@guymcarthur.com>.
I like some of the things in the tutorial, but I don't want to do XForms,
or XSP, or describe form validation in XML. Just want to map requests to
java beans. Beans set their mode (state) as a parameter to the stylesheet,
and the stylesheet has templates for each mode. The useBean syntax of jsp
makes it easy, but if the cocoon sitemap can do that too, eliminating the
jsp would be good.
What would be ideal, is using JXPath and eliminating the bean marshalling
to xml step altogether.
It seems like Actions could do this, but it's unclear....
Say for a simple example, a "guess a number" web application with one bean
and one corresponding stylesheet.
This outlines the kind of thing I'd like to be able to do.
--
public class GuessGame {
private int target, guess, steps = 0;
private boolean hasGuessed;
private String action; // value of form submit
public GuessGame() {
this.target = (int)Math.random(100);
}
public void setAction(String action) {
this.action = action;
}
public String getMode() {
if(action.equals("Cancel")) return "cancel";
else if(haveGuessed) {
return (guess == target) ? "final" : "guessing";
} else return "initial";
}
public int getGuess() {
return guess;
}
public void setGuess(int guess) {
this.guess = guess;
haveGuessed = true;
++steps;
}
}
--
<%-- Have some way to map requests to bean logic.
With the bean data available to the stylesheet.
--%>
<jsp:useBean name="game" class="GuessGame" scope="session"/>
<jsp:setProperty id="game" name="*"/>
--
<xsl:stylesheet>
<xsl:template match="game" mode="initial">
Hit Next to begin the game or Quit to close.
<form>
<input type="submit" name="action" value="Next"/>
<input type="submit" name="action" value="Quit"/>
</form>
</xsl:template>
<xsl:template match="game" mode="guessing">
Sorry! <xsl:value-of select="@guess"/> was
<xsl:choose>
<xsl:when test="@guess > @target">
too high.
</xsl:when>
<xsl:otherwise>
too low.
</xsl:otherwise>
</xsl:choose>
Guess again.
<form>
<input type="text" name="guess" value="{@guess}"/>
<input type="submit" name="action" value="Next"/>
<input type="submit" name="action" value="Quit"/>
</form>
</xsl:template>
<xsl:template match="game" mode="final">
You got it in <xsl:value-of select="@steps"/> steps!
<form>
<input type="submit" name="action" value="Quit"/>
</form>
</xsl:template>
<xsl:template match="game" mode="quit">
Thanks for playing.
</xsl:template>
</xsl:stylesheet>
--
Anyways, I'd like to do something like that, but what components go in the
middle between beans and xsl is a mystery....
---------------------------------------------------------------------
Please check that your question has not already been answered in the
FAQ before posting. <http://xml.apache.org/cocoon/faq/index.html>
To unsubscribe, e-mail: <co...@xml.apache.org>
For additional commands, e-mail: <co...@xml.apache.org>
Re: [USER POLL] New cocoon-docs mailing list?
Posted by Martin Stricker <sh...@gmx.de>.
Nicola Ken Barozzi wrote:
> Users, do you think it's time for a cocoon-docs list?
-0
Documentation (at least the first draft) is best written by the person
who is most accustomed to the code, so that's usually the developer
her/himself. So I *think* cocoon-dev is the best place to discuss
documentation issues. However, as long as no developer
*ignores/"forgets"* documentation, if documentation issues come to a
huge mail count, a separate mailing list *might* be useful. Hence the
negative zero vote...
Best regards,
Martin Stricker
--
Homepage: http://www.martin-stricker.de/
Webmaster-Forum: http://www.masterportal24.com/cgi-bin/YaBB.cgi
Red Hat Linux 7.2 for low memory: http://www.rule-project.org/
Registered Linux user #210635: http://counter.li.org/
---------------------------------------------------------------------
Please check that your question has not already been answered in the
FAQ before posting. <http://xml.apache.org/cocoon/faq/index.html>
To unsubscribe, e-mail: <co...@xml.apache.org>
For additional commands, e-mail: <co...@xml.apache.org>
Re: [USER POLL] New cocoon-docs mailing list?
Posted by "Andrew C. Oliver" <ac...@apache.org>.
>
> *******************************************************
>
> Users, do you think it's time for a cocoon-docs list?
>
> *******************************************************
>
-1 - I consider myself 3/4 cocoon user and 1/4 developer. So count my
vote for 3/4. I think
having a cocoon-docs list will detract from the goal of having
documentation. Certain personalities
in the group will be able to avoid the documentation issue entirely,
where keeping the development
concerns (meaning the development of documentation) IN the development
list will keep the issue in
their face.
I'll only vote for it if the list can be called
cocoon-lets-brush-documentation-under-the-rug@xml.apache.org
which in my opinion would be what the list was for! (despite any best
intentions).
-Andy
---------------------------------------------------------------------
Please check that your question has not already been answered in the
FAQ before posting. <http://xml.apache.org/cocoon/faq/index.html>
To unsubscribe, e-mail: <co...@xml.apache.org>
For additional commands, e-mail: <co...@xml.apache.org>
Re: [USER POLL] New cocoon-docs mailing list?
Posted by Mike Haarman <mh...@socsci.umn.edu>.
+1
There is no reason for Cocoon not to be the best documented package
under //xml.apache.org/ The pipeline for documentation should be the best
example of how to use the system.
And somehow, documenting the documentation system seems quite in spirit
with the project and its markup foundation: all things consumed in an
ever-widening vortex of referentiality.
----------------------------------------------------------------
Mike Haarman
mhaarma@socsci.umn.edu
Maintainer,
DDI Codebook DTD -- http://www.icpsr.umich.edu/DDI/
---------------------------------------------------------------------
Please check that your question has not already been answered in the
FAQ before posting. <http://xml.apache.org/cocoon/faq/index.html>
To unsubscribe, e-mail: <co...@xml.apache.org>
For additional commands, e-mail: <co...@xml.apache.org>
Re: [COCOON] New cocoon-docs mailing list
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Sam Ruby wrote:
> Nicola Ken Barozzi wrote:
>
>> Dear PMC, Dear root,
>>
>> The Cocoon project asks for the creation of a new mailing list to aid
>> the new Cocoon Documentation project.
>>
>> cocoon-docs@xml.apache.org
>
> List created, Initial moderator is nicolaken@apache.org.
Thank you, Sam! :-)
For all users and developers that want to work on the documentation,
just send an empty mail to:
cocoon-docs-subscribe@xml.apache.org
Let's roll! :-D
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [COCOON] New cocoon-docs mailing list
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Sam Ruby wrote:
> Nicola Ken Barozzi wrote:
>
>> Dear PMC, Dear root,
>>
>> The Cocoon project asks for the creation of a new mailing list to aid
>> the new Cocoon Documentation project.
>>
>> cocoon-docs@xml.apache.org
>
> List created, Initial moderator is nicolaken@apache.org.
Thank you, Sam! :-)
For all users and developers that want to work on the documentation,
just send an empty mail to:
cocoon-docs-subscribe@xml.apache.org
Let's roll! :-D
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
---------------------------------------------------------------------
Please check that your question has not already been answered in the
FAQ before posting. <http://xml.apache.org/cocoon/faq/index.html>
To unsubscribe, e-mail: <co...@xml.apache.org>
For additional commands, e-mail: <co...@xml.apache.org>
Re: [COCOON] New cocoon-docs mailing list
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Sam Ruby wrote:
> Nicola Ken Barozzi wrote:
>
>> Dear PMC, Dear root,
>>
>> The Cocoon project asks for the creation of a new mailing list to aid
>> the new Cocoon Documentation project.
>>
>> cocoon-docs@xml.apache.org
>
> List created, Initial moderator is nicolaken@apache.org.
Thank you, Sam! :-)
For all users and developers that want to work on the documentation,
just send an empty mail to:
cocoon-docs-subscribe@xml.apache.org
Let's roll! :-D
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: [COCOON] New cocoon-docs mailing list
Posted by Sam Ruby <ru...@intertwingly.net>.
Nicola Ken Barozzi wrote:
> Dear PMC, Dear root,
>
> The Cocoon project asks for the creation of a new mailing list to aid
> the new Cocoon Documentation project.
>
> cocoon-docs@xml.apache.org
List created, Initial moderator is nicolaken@apache.org.
- Sam Ruby
P.S. No need to bother root for mail requests, apmail@apache.org will do.
---------------------------------------------------------------------
Please check that your question has not already been answered in the
FAQ before posting. <http://xml.apache.org/cocoon/faq/index.html>
To unsubscribe, e-mail: <co...@xml.apache.org>
For additional commands, e-mail: <co...@xml.apache.org>
Re: [COCOON] New cocoon-docs mailing list
Posted by Sam Ruby <ru...@intertwingly.net>.
Nicola Ken Barozzi wrote:
> Dear PMC, Dear root,
>
> The Cocoon project asks for the creation of a new mailing list to aid
> the new Cocoon Documentation project.
>
> cocoon-docs@xml.apache.org
List created, Initial moderator is nicolaken@apache.org.
- Sam Ruby
P.S. No need to bother root for mail requests, apmail@apache.org will do.
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
[COCOON] New cocoon-docs mailing list
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Dear PMC, Dear root,
The Cocoon project asks for the creation of a new mailing list to aid
the new Cocoon Documentation project.
cocoon-docs@xml.apache.org
This project will stand for Cocoon as the HTTP Server Documentation
Project does with the HTTP Server Project.
For coordinating the project, Diana Shannon has already been made
committer with a very big number of votes, and is working very actively
with the collaboration of both users and developers.
http://marc.theaimsgroup.com/?t=101896493700004&r=1&w=2
The creation of this list has been voted positively by the developer
list after some discussion, since we were not sure that there was a
community of doc writers for Cocoon.
+1 6 votes from committers, 3 from users-developers
+0 3 votes
http://marc.theaimsgroup.com/?t=102068666400002&r=1&w=2
Because of this, we have not asked for the creation of the list right
away, waiting instead to see how much involvement the doc effort was
able to generate.
These weeks have clearly shown that there is a great need for better
documetation and a good number of users and developers already working
on it with success.
In fact the volume of the documentation mails has recently topped the
one of other topics on the user list.
Because of this, we asked the users if it was time to start the docs list.
> At 14:09 28/06/2002 +0200, Nicola Ken Barozzi wrote:
>
>> The Cocoon documentation project has started with the great help of
>> Diana Shannon, and is gaining good momentum and interest :-)
>>
>> In case you don't already know, on the dev list we have decided that a
>> cocoon-docs mailing list could help this subproject and facilitate
>> contributors.
>>
>> We are *seriously* committed to Cocoon, and to the *best*
>> documentation it can have.
>>
>> *******************************************************
>>
>> Users, do you think it's time for a cocoon-docs list?
>>
>> *******************************************************
Result of this poll was
+1 9 votes
-0 1 vote
-1 1 vote
http://marc.theaimsgroup.com/?t=102526636100001&r=1&w=2
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
---------------------------------------------------------------------
Please check that your question has not already been answered in the
FAQ before posting. <http://xml.apache.org/cocoon/faq/index.html>
To unsubscribe, e-mail: <co...@xml.apache.org>
For additional commands, e-mail: <co...@xml.apache.org>
[COCOON] New cocoon-docs mailing list
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Dear PMC, Dear root,
The Cocoon project asks for the creation of a new mailing list to aid
the new Cocoon Documentation project.
cocoon-docs@xml.apache.org
This project will stand for Cocoon as the HTTP Server Documentation
Project does with the HTTP Server Project.
For coordinating the project, Diana Shannon has already been made
committer with a very big number of votes, and is working very actively
with the collaboration of both users and developers.
http://marc.theaimsgroup.com/?t=101896493700004&r=1&w=2
The creation of this list has been voted positively by the developer
list after some discussion, since we were not sure that there was a
community of doc writers for Cocoon.
+1 6 votes from committers, 3 from users-developers
+0 3 votes
http://marc.theaimsgroup.com/?t=102068666400002&r=1&w=2
Because of this, we have not asked for the creation of the list right
away, waiting instead to see how much involvement the doc effort was
able to generate.
These weeks have clearly shown that there is a great need for better
documetation and a good number of users and developers already working
on it with success.
In fact the volume of the documentation mails has recently topped the
one of other topics on the user list.
Because of this, we asked the users if it was time to start the docs list.
> At 14:09 28/06/2002 +0200, Nicola Ken Barozzi wrote:
>
>> The Cocoon documentation project has started with the great help of
>> Diana Shannon, and is gaining good momentum and interest :-)
>>
>> In case you don't already know, on the dev list we have decided that a
>> cocoon-docs mailing list could help this subproject and facilitate
>> contributors.
>>
>> We are *seriously* committed to Cocoon, and to the *best*
>> documentation it can have.
>>
>> *******************************************************
>>
>> Users, do you think it's time for a cocoon-docs list?
>>
>> *******************************************************
Result of this poll was
+1 9 votes
-0 1 vote
-1 1 vote
http://marc.theaimsgroup.com/?t=102526636100001&r=1&w=2
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [USER POLL] New cocoon-docs mailing list?
Posted by Bert Van Kets <be...@vankets.com>.
+1 from me. Maybe some more users (me included) will get some more focus
on docs. I have some texts laying around I need to finish to be useful.
Bert
At 14:09 28/06/2002 +0200, you wrote:
>The Cocoon documentation project has started with the great help of Diana
>Shannon, and is gaining good momentum and interest :-)
>
>In case you don't already know, on the dev list we have decided that a
>cocoon-docs mailing list could help this subproject and facilitate
>contributors.
>
>We are *seriously* committed to Cocoon, and to the *best* documentation it
>can have.
>
> *******************************************************
>
> Users, do you think it's time for a cocoon-docs list?
>
> *******************************************************
>
>
>--
>Nicola Ken Barozzi nicolaken@apache.org
> - verba volant, scripta manent -
> (discussions get forgotten, just code remains)
>---------------------------------------------------------------------
>
>
>---------------------------------------------------------------------
>Please check that your question has not already been answered in the
>FAQ before posting. <http://xml.apache.org/cocoon/faq/index.html>
>
>To unsubscribe, e-mail: <co...@xml.apache.org>
>For additional commands, e-mail: <co...@xml.apache.org>
---------------------------------------------------------------------
Please check that your question has not already been answered in the
FAQ before posting. <http://xml.apache.org/cocoon/faq/index.html>
To unsubscribe, e-mail: <co...@xml.apache.org>
For additional commands, e-mail: <co...@xml.apache.org>
[USER POLL] New cocoon-docs mailing list?
Posted by Nicola Ken Barozzi <ni...@apache.org>.
The Cocoon documentation project has started with the great help of
Diana Shannon, and is gaining good momentum and interest :-)
In case you don't already know, on the dev list we have decided that a
cocoon-docs mailing list could help this subproject and facilitate
contributors.
We are *seriously* committed to Cocoon, and to the *best* documentation
it can have.
*******************************************************
Users, do you think it's time for a cocoon-docs list?
*******************************************************
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
---------------------------------------------------------------------
Please check that your question has not already been answered in the
FAQ before posting. <http://xml.apache.org/cocoon/faq/index.html>
To unsubscribe, e-mail: <co...@xml.apache.org>
For additional commands, e-mail: <co...@xml.apache.org>
Re: docs & misc
Posted by Mikhail Fedotov <mi...@kittown.com>.
Hi!
I've spend several hours writing an answer, and my computer
crashed... damn. So I've tried to be as much short and
practical as possible. It took two more hours. Damn. :)
> And yes, I've written guidelines about each of them. See
> http://xml.apache.org/cocoon/howto/
About 'How to Author a How-To'.
Here is one obvious place there the SCORE could be applied
(with some mods), I'm talking about 'overview' section. The
application can be done in the form of blank with the
following questions: that is the situation where this howto
is useful (4example, large amount of static documents),
what do we want to do (enable caching), that do we hope to
get by doing that (faster response times), that could/is
preventing us from doing that (not enough memory) and that
steps must be done (changing config), and that will help us
to do that (different caching mechanisms implemented in
cocoon, with an option to keep cached documents on memory
or on harddrive).
You can judge by yourself where those questions are useful.
I've studied other parts of howto, score is all over the
place, but in most cases only one or two questions are
required, so the whole model isn't needed. And it isn't
needed in any other form except for those questions.
The next addition is the step-by-step guide on how to
create docs. I.e. there shouldn't be just a long verbose
list of guidelines, but the list of first 4-5 tasks to
complete first version of howto (and publish it), and
recommendations on it's future refining. Current list of
guidelines looks like the list of mandatory requirements
and distracts a bit. Well, 'distracts alot' will be more
correct. ;) Just complement it with minimalistic
instruction with a clear distinction between general
guidelines and steps to author an how-to. Now they are
mixed, and it is very funny to read in the _first_ (by
order) _step_ that it is actually the _last_ one. :)
> >If you could create advanced documentation as easy as
> >basicget-started-in-a-minute howtos, there would be more
> >advanced documentation. Document templates (with SCORE
> >installed in form of questions), blanks, any other
> >automation could help if implemented wisely.
>
> Is there an example of this anywhere on the web?
I doubt, except that you can find a book about history of
the whole idea of blanks. It is an interesting story and a
there are good examples of proper applying of blanks idea.
Bureaucracy is an example of incorrect applying.
If we are talking about docs generation for some already
written software, score is reduced to several questions
(mentioned above) that can help us to create an effective
blank, and that's it.
> <snip what="stuff about SCORE" why="need link" />
The net contains usage in therapy mostly. :) The model
itself is obvious enough to be reinvented and used under
different name in other contexts, but I don't know that
name.
> Still, if people know enough about Cocoon to write
> docs, they should be comfortable creating a
> document.dtd-compliant XML pages as contributions and
> submitting via Bugzilla. We have How-To instructions for
> all of that.
I fear they won't go for it. You require too much
motivation from them. Let's wait for Forrest & forms...
> Send us a link about SCORE, or about web-based approaches
> using SCORE, and I'll be more than happy to have a look.
I've reduced it to some basic question for this particular
case of writing docs; otherwise we could end up discussing
it for too long. It wasn't a wise decision to mention SCORE
here, my apologies. Hope those questions will be useful. :)
Mikhail
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: docs & misc
Posted by Diana Shannon <sh...@apache.org>.
On Thursday, June 27, 2002, at 05:01 PM, Mikhail Fedotov wrote:
> Hi!
>
>> Well why don't you check out wiki dictionary effort made
>> with Cocoon? Perhaps you could help build that
>> dictionary. http://www.anyware-tech.com/wikiland/
>
> Wiki is an entirely different thing, I believe.
Of course, but there are many ways to contribute to Cocoon. I was just
trying to channel your concerns/interest into more tangible activities.
Other people read these threads, so it's also a notice to them as well.
>> Try not to jump to conclusions about why the state of
>> documentation is what it currently is.
>
> I know the documentation. All of it, except parts that I've
> already forgot since last reading.
Of course you do. What I was suggesting is that don't assume you know
the historical reasons (dynamics) which resulted in the current state of
the docs. I'm not trying to lecture you; I made the same mistake
myself ... really. I've discovered it's far more complicated than I
originally thought. Any current "state" is a result of what has happened
in the past. There are a multitude of factors which contributed to this
state over time. Weak structure is but one of many, and I agree that an
improved doc structure will help. We are working on many of these issues
in Forrest. Your contributions there would be greatly appreciated. In
some ways, work with Forrest has slowed the doc content improvement
effort here at Cocoon. But it's better for the long term.
>
>> I could add a hundred items to your list.
>
> Well, my first point was about simplification of docs
> creation, and second point was the model to describe
> things. I can't add those hundreds of items, I just have
> a few simple and maybe not so obvious ones in mind. I'm
> normal (i.e. extremely lazy) guy, and I know the way of
> writing documentation that I would be comfortable with. And
> since I believe that I'm not alone, I share my ideas about
> it. I'm not inventing anything, I'm too lazy to do that. :)
Yea, yea. Everyone *says* they are "lazy", that's why they program. This
is nuts. Some of the so-called laziest people I know contribute to open
source in a superhuman way. Look, not everyone feels "lazy" about docs.
It won't take an army of people to improve Cocoon core docs, just more
than we have at this time. For example, the Apache docs project has
about 11 active committers. New authors just need to start emerging from
the haze of userland.
>
>> When more people come forward to help improve existing
>> docs, and contribute new docs, then they will improve.
>> No sooner and no later.
>
> I wouldn't be sure about it. I believe in community, but
> there is enough cases to study - JBoss, Tomcat, Struts.
> Even the most popular tools usually don't have finished and
> complete documentation.
Yes, and we can learn from their mistakes. That's the beauty. Also, I
believe we have a more diverse user base with Cocoon. And the above
technologies you mention are in many ways more developer-oriented.
Cocoon is great for publishing concerns. Many people in the publishing
field happen to know a thing or two about how to make good docs. I'm
convinced such people exist. But there are many other flavors of users
who can contribute docs.
> On the other hand, they have alot
> of documentation of some kind, and it seems to be a good
> idea to remember this.
Qualify what you mean by a lot. A lot of what? Here's what I want:
- more FAQs, no limit
- more Snippets, no limit
- more How-Tos, no limit
- more <other doc here>, but no time to provide instructions yet
What in the world is wrong with "a lot" of the above? They are
deliberately granular, building blocks for more complicated docs down
the road. They don't take much time to write. They are
community-oriented, not necessarily "committed author"-oriented. Do you
see the difference?
And yes, I've written guidelines about each of them. See
http://xml.apache.org/cocoon/howto/
I welcome your suggestions on how to improve these guidelines. I didn't
just make them up. I went out and researched how other people structured
similar docs.
As for core docs, I want more than we have right now, but it won't take
lots more. Just filling in content gaps and extending many docs to
include more examples, better summaries, etc. will go a long way. We
have a proposed outline. You can view it in the cvs at
http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-
cocoon2/src/documentation/xdocs/drafts/newtoc.txt?rev=1.1
However, I (speaking only for myself) am *not* going to work on this
until Cocoon has made the transition to Forrest.
> If you could create advanced documentation as easy as basic
> get-started-in-a-minute howtos, there would be more
> advanced documentation. Document templates (with SCORE
> installed in form of questions), blanks, any other
> automation could help if implemented wisely.
Is there an example of this anywhere on the web?
>
>> There is an effort at Apache Forrest to improve
>> underlying documentation architecture. If you
>> don't want to contribute new/revised docs to the Cocoon
>> project, perhaps you'd be interested in supporting that
>> project's architectural efforts?
>
> Forrest seems to me like an overkill, but I like it and
> hope it will be finished.
I couldn't disagree with you more. Among many other things, Forrest
brings automation to a lot of very tedious and error-prone doc-related
tasks. It has a number of interesting tools, such as libre, a directory
generator on steriods. A lot of careful thought has gone into its
document dtds. I've adopted the Forrest/Krysalis-Centipede approach for
a few projects of mine already, and it's brought a number of benefits.
It's a very clean way to set up a project. After a few minutes of cvs
training, people with low-level XML skills can make a big contribution
to your project. Add a few interesting build targets from
Krysalis-Centipede, and -- presto-- you have a first-rate doc and
project architecture.
> I'me not sure that I'll do. I've just wanted to give some
> hints that could help with a few of major documentation
> writing-related problems. They are working already here and
> there. Maybe I'll download Forrest and check it out.
Well, tell us where they are working, and I'll be more than happy to
check them out, really.
<snip what="stuff about SCORE" why="need link" />
> Check out other open source projects, you can see that kind
> of documentation complexity and completeness you
> can expect. _If_ you could provide _good_ guidelines to
> write those docs and made this process _simple_ (maybe like
> filling in a blank), then, taking into account growing
> popularity of cocoon2, you could get those authors.
I agree we need guidelines. I have created some already. Cocoon can't
have a dynamic site at this time, so we have no way to process
form-based document contributions *yet*. Still, if people know enough
about Cocoon to write docs, they should be comfortable creating a
document.dtd-compliant XML pages as contributions and submitting via
Bugzilla. We have How-To instructions for all of that.
Send us a link about SCORE, or about web-based approaches using SCORE,
and I'll be more than happy to have a look.
Thanks for expressing your ideas about how to improve the documentation.
Diana
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: docs & misc
Posted by Mikhail Fedotov <mi...@kittown.com>.
Hi!
> Well why don't you check out wiki dictionary effort made
> with Cocoon? Perhaps you could help build that
> dictionary. http://www.anyware-tech.com/wikiland/
Wiki is an entirely different thing, I believe.
> Try not to jump to conclusions about why the state of
> documentation is what it currently is.
I know the documentation. All of it, except parts that I've
already forgot since last reading.
> I could add a hundred items to your list.
Well, my first point was about simplification of docs
creation, and second point was the model to describe
things. I can't add those hundreds of items, I just have
a few simple and maybe not so obvious ones in mind. I'm
normal (i.e. extremely lazy) guy, and I know the way of
writing documentation that I would be comfortable with. And
since I believe that I'm not alone, I share my ideas about
it. I'm not inventing anything, I'm too lazy to do that. :)
> When more people come forward to help improve existing
> docs, and contribute new docs, then they will improve.
> No sooner and no later.
I wouldn't be sure about it. I believe in community, but
there is enough cases to study - JBoss, Tomcat, Struts.
Even the most popular tools usually don't have finished and
complete documentation. On the other hand, they have alot
of documentation of some kind, and it seems to be a good
idea to remember this.
If you could create advanced documentation as easy as basic
get-started-in-a-minute howtos, there would be more
advanced documentation. Document templates (with SCORE
installed in form of questions), blanks, any other
automation could help if implemented wisely.
> There is an effort at Apache Forrest to improve
> underlying documentation architecture. If you
> don't want to contribute new/revised docs to the Cocoon
> project, perhaps you'd be interested in supporting that
> project's architectural efforts?
Forrest seems to me like an overkill, but I like it and
hope it will be finished.
I'me not sure that I'll do. I've just wanted to give some
hints that could help with a few of major documentation
writing-related problems. They are working already here and
there. Maybe I'll download Forrest and check it out.
> I have built a lot of models in my professional life, and
> I'm not sure I would be so brave as to model open source
> community dynamics ... ;-)
This model is used in therapy. It is the model for changes
- that we have, that we want, that we hope to get, that is
preventing us from doing that, and that resources could
help with that. Problem often goes away right after the
client wrote those five points how he thinks about them.
One guy we've been discussing recently had used it in
rocket-science course and won an award as the writer of the
best course in that year. The methods for describing each
of points are important to get it working, it has complex
origins.
It is not a panacea, but a very productive model. I'll just
highly recommend to check it out; it is one of those little
things that affect the whole way of thinking. If you are
interested, I could point where to look for more accurate
information, and if you aren't, it would be better to stop
at this point. :) [*]
> <snip />
> >Symptoms - complex webapp, many documents, big
> >hierarchy, difficulties with all this; some
> >paragraphs about it.
>
> I don't agree that a complex webapp is a "symptom" of a
> problem.
It is part of description of state where the problem
arises, where we are starting at. BTW, I've been talking
about the _form_ of information presentation, but you are
talking about information itself. We are talking about
different topics. :) See [*].
> You can have all the structure in the world but you still
> need writers. IMHO, the hardest part is writing well. If
Check out other open source projects, you can see that kind
of documentation complexity and completeness you
can expect. _If_ you could provide _good_ guidelines to
write those docs and made this process _simple_ (maybe like
filling in a blank), then, taking into account growing
popularity of cocoon2, you could get those authors.
For example, there is many useful info in javadocs, but not
in general documentation pages. Maybe it is just because
there are defined good guidelines for writing javadocs ?
Such rules _must_ be simple, and if we are talking about
javadoc writing rules, they are. And there are many
javadocs authors out there. :)
SCORE is a different beast. It pays off, but requires
adoption and understanding. It is for more general docs,
not for simple components descriptions. It isn't easy to
teach every author about it, but it can help you with
writing guidelines, as a minimum. See [*] again. :)
> >Resources - use of SoC pattern with Cocoon2 as a tool,
> >transforming the hierarchy into tree with no dependency
> >between branches; some paragraphs about it.
>
> What do you mean by hierarchy?
I've been talking about general url and site structure and
their mappings onto an application structure. This one is
far away from the subject.
Mikhail
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: docs & misc
Posted by Diana Shannon <sh...@apache.org>.
On Thursday, June 27, 2002, at 02:34 AM, Mikhail Fedotov wrote:
>> After just a few hours of poking around I have decided
>> that it will be much simpler for me to simply hand-code
>> a whole hat-full of servlets than to try and pull any
>> meaning out of Cocoon and it's documentation.
>
> Two things to mention:
>
> 1. I've been talking here about documentation in form of
> dictionary, where is no structure and long docs, just
> complete descriptions of components and their parameters;
> it is the quick way to produce complete components
> documentation that helps in creation of more complex
> documentation. If someone will become interested in
> lowering the difficulty of writiting docs (that I've been
> talking about), and not just writing another docs page
> (that I've been told to do as an response), he could arise
> that topic again.
Well why don't you check out wiki dictionary effort made with Cocoon?
Perhaps you could help build that dictionary.
http://www.anyware-tech.com/wikiland/
> 2. About the current docs. They aren't _that_ bad, there is
> much of information. But it looks more like an student
> work, i.e. it gives impression of work made, but not
> optimized for easy understanding and using.
Try not to jump to conclusions about why the state of documentation is
what it currently is. I made that mistake earlier on this list. ;-) I
continue to learn new factors almost every day why producing good docs
is difficult in this context. I could add a hundred items to your list.
Think of the quality of docs as an indicator of a community's evolution.
When more people come forward to help improve existing docs, and
contribute new docs, then they will improve. No sooner and no later. If
this keeps Cocoon from reaching new audiences, then that's just a
result -- it isn't necessarily a problem, just a phase of growth. There
is an effort at Apache Forrest to improve underlying documentation
architecture. If you don't want to contribute new/revised docs to the
Cocoon project, perhaps you'd be interested in supporting that project's
architectural efforts?
http://xml.apache.org/forrest/
> Here is one
> good model usable in too much contexts to mention, and it
> is also good in writing docs:
I have built a lot of models in my professional life, and I'm not sure I
would be so brave as to model open source community dynamics ... ;-)
<snip />
> Symptoms - complex webapp, many documents, big hierarchy,
> difficulties with all this; some paragraphs about it.
I don't agree that a complex webapp is a "symptom" of a problem. I think
the problem that Cocoon is trying to solve is complex. As for "many
documents," I agree some could be refactored however isn't going to
happen until Cocoon migrates to a Forrest architecture (in process
already). At the point, many more options to improve the docs structure
will become available to us. It just takes time when everyone is a
volunteer. We are also making the best of available resources, which at
the present time, includes a static web site.
Still, I prefer more docs. I don't think there are too "many" docs. I
also want to increase the author pool. With difficult, complex subjects
like Cocoon, sometimes you need multiple voices to say the same thing,
just a bit differently. When you are learning something new, and you
have the luxury of buying books, wouldn't you prefer to buy more than
one, even if it's about the same topic?
> Causes - hierachy isn't structured, components dependence
> is out-of-control, bad code reuse, too much amount of
> everything, etc; some paragraphs about it.
>
> Outcome - doing things in a more structured way; some
> paragraphs about it.
You can have all the structure in the world but you still need writers.
IMHO, the hardest part is writing well. If we make writing "easy" by
removing so-called architectural obstacles, does that mean we'll
automatically have "good" content? I'm not sure about this. Don't get me
wrong, I think architectural improvements will help immensely. However,
you probably are aware that many authors have the additional challenge
of having to write in a non-native language. Regardless of what you
think about the docs, I really admire the people who have contributed
docs so far. And I'm also excited about the books coming out.
> Resources - use of SoC pattern with Cocoon2 as a tool,
> transforming the hierarchy into tree with no dependency
> between branches; some paragraphs about it.
What do you mean by hierarchy? The documentation hierarchy? If you are
concerned about 2.1 docs being made available with 2.03 docs, then isn't
it enough to note, in very clear and visual terms, what content applies
to what branch? The 2.1 docs we have are very good. I think they help
users understand some of the great stuff that is going on in the HEAD
branch. As long as they are warned, I don't see the problem.
Diana
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org