cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Mikhail Fedotov" <mikh...@kittown.com>
Subject Re: docs & misc
Date Thu, 27 Jun 2002 21:01:13 GMT
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


Mime
View raw message