cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <shan...@apache.org>
Subject Re: docs & misc
Date Fri, 28 Jun 2002 12:02:31 GMT

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


Mime
View raw message