cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <cross...@apache.org>
Subject RE: Documentation TOC started
Date Sat, 17 Apr 2004 12:02:02 GMT
H.vanderLinden wrote:
> David Crossley wrote:
> > 
> > ...This is then orthogonal to the total 
> > restructuring of the xdocs, which was shelved until 2.2 
> > because it would otherwise break our URL space.
> 
> AHA. That explains the "complete radio silence" when it comes to updating
> the documentation. :-)

No, not really that. Documentation can be enhanced totally
independent of any restructure.

I am lost in attempting to understand why very little contributions
to existing documentation are being made by the community.

Quite a few of us have attempted to deal with the documentation.
Don't let that discourage you ... keep on.

> > I would certainly like to see this ToC cater for the 
> > anticipated "Reference documentation" (cannot find old dev@ 
> > or old docs@ discussion yet).
> 
> What exactly do you mean by "reference documentation"? To me it's a mixture
> of JavaDocs + extra explanation + textual examples and maybe even a live
> working example in the "samples" section.

That is right, something along those lines. Automatically generated
by extracting certain Javadoc tags and supplementing with other info.
There are discussions about it in the dev or initial docs mail archive.

<snip/>
> > One thing that we had discussed about Cocoon core xdocs 
> > documentation was that it should not appear to sanctify any 
> > external documentation, because there is some stuff out there 
> > that we may not be happy with and where do we draw the line. 
> 
> Hmm, maybe it's simply my understanding of English, but I don't really
> understand what you mean here. Do you mean that "no" external reference
> should be included or "all"?

I mean that our core documentation, i.e. the xdocs and the key Wiki
pages, should be be written by this community and should be the
definitive view on the topic.

In general we should not make links to outside documentation because
we have absolutely no control over what they say about Cocoon. They
might have some good statements then a heap of misguided statements.
We would be leading the users astray because our core documentation
would appear to recommend that document as some authority.

Besides that, constantly changing URLs and dead links are too hard
to manage over time.

I think the best solution is to have very few references to external
documentation about Cocoon. We would have a set of community-supported
Wiki pages for that.

> I was thinking along this line:
> - references to external URLs that explain "add-ins" for Cocoon, e.g. the
> flowscript debugger, the Sunbow plugins for Eclipse etc.
> - references to blog entries which explain some otherwise hard to find info.
> - references to mail archives.
> - references to articles on Cocoon (e.g. the TSS article lately)
> - anything else I've forgotten
> 
> The latter 2 are stuff for the Wiki page.
> For the first 3 I'm thinking of getting in touch with the original authors
> and ask permission to include/rewrite the information and include it in the
> Cocoon xdoc itself. When components are involved, links are included to the
> authors pages for more info and downloads.

It is the external links that can lead to problems.

> This would be my option, because I've experienced myself numerous times
> where I "searched myself colorblind" to find information on a certain topic,
> only to stumble across it in a totally unrelated description or after much
> mailing back and forth on the mailing list.
> For me a good product has 2 main aspects: 1. It works more or less out of
> the box and works as expected, 2. If not, there is a good manual where I can
> look (most) things up. From my POV Cocoon has (1), but lacks (2) in the sens
> that the information is probably "somewhere", but it cannot be found easily.

Sure. You are "preaching to the converted" on cocoon-dev :-)

--David

> > Also we do not want to get into URL management and dead 
> > links. So yes, a separate Wiki page sounds better.
> 
> My idea.
> 
> > There is one aspect that i am still not clear about. Do you 
> > envisage that this ToC itself would become an xdoc? I hope so. 
> 
> Yes. Every book needs a ToC, an ebook even more so. In fact, it would also
> need an index. (sigh, even more work :-) ).
> 
> > If so, then that is why i would like it to be free from 
> > references to external cocoon-related stuff.
> 
> Ok, I'll start a new Wiki page.
> 
> Bye, Helma


Mime
View raw message