cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bruno Dumon <br...@outerthought.org>
Subject Re: [Ann] New Documentation Structure
Date Mon, 01 Sep 2003 18:45:29 GMT
On Mon, 2003-09-01 at 10:14, Carsten Ziegeler wrote:
> Hi Team,
> 
> we have been talking recently about our marketing strategy for Cocoon.
> Now, I think one major advantage other projects have is their good
> documentation. Often people don't choose a project because of the
> technical value but because of a good documentation.
> 
> So, in the last days I refactored our documentation a little bit
> and updated some sections. It now looks a little bit like a real
> manual. We have a lot of documentation but it's spread all over
> the place and is not really good structured.
> 
> You can see this documentation in CVS in the xdocs/userguide
> directory. It contains all the docs from xdocs/userdocs, 
> xdocs/developing and the performance-tips in a restructured way.
> So I copied all the docs and edited some of them.
> 
> It is only a beginning to show the difference. I will try and update 
> the sections one after the other in the next weeks. 
> 
> Please have a look at it and tell me, if this new version can replace
> the old userdocs/developing sections. If yes, I would remove the old
> dirs and rename the userguide to userdocs.
> 
> PS: It might be that some links are not correct in the new version,
> but they can be fixed easily.

Carsten,

first of all: thanks for starting this important job. I was looking at
our site recently and was getting the same itch...

I can't say I really like all about the new structure though...

There will of course always be many ways to structure the documentation,
but my idea is to basically structure it as the code is organized:

* basic topics, covering stuff in cocoon-core (both conceptual docs &
docs on core components, and installation instructions, or in short,
everything that does not belong to a specific block)
* documentation on the various blocks

So I'd also remove any split between user and developer docs, or between
basic and advanced topics.

I think this will make the relevant documentation easier to find and
easier to maintain.

What do you think?


BTW: anyone against moving to documentv12 DTD for all our docs? I'm more
used to working with that one, and have my XXE environment set up for
that, so it would lower the barrier for me...

-- 
Bruno Dumon                             http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
bruno@outerthought.org                          bruno@apache.org


Mime
View raw message