cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject RE: Documentation TOC started
Date Sun, 18 Apr 2004 18:45:12 GMT
> 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.

Aha, that's a clear point. Especially the latter. I currently have a feeling
that definitive views on several topics are changing (e.g. flow vs actions,
jx vs xsp), it would be nice to get certain things down "in writing" to make
it easier to decide on which "learning curve" to take.
> 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.

True, on the other hand I think that a good product can defend itself and
linking to "the enemy" might just as well be an indication of that. Sure,
this shouldn't be included in the core documents, but a Wiki page with such
links (e.g. the TSS article lately AS WELL AS the discussions about it, both
here and on the TSS article reviews) might prove to be just enough to
newbies to decide to start with Cocoon or to drop it before getting into it.

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

Right, although I find that less irritating in a Wiki page than in the

> > 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.

Yes, but how to include information on e.g. the sunbow plugins for Eclipse?
Either the you include the entire text in the xdocs (with the authors'
permission of course), but are still left with links to the actual code, or
you need to refer to Wiki pages (which are currently changing URL :-) )
which contain such information.

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

Sorry, I'm used to the male technical geeks that write better code than
their native language. And usually consider code enough documentation
anyway. ;-)

Bye, Helma

View raw message