You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@cocoon.apache.org by Carsten Ziegeler <cz...@s-und-n.de> on 2003/09/01 10:14:34 UTC
[Ann] New Documentation Structure
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
Carsten Ziegeler
Open Source Group, S&N AG
http://radio.weblogs.com/0107211/
Re: [Ann] New Documentation Structure
Posted by Tony Collen <co...@umn.edu>.
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.
Carsten,
Thank you for taking the initiative in this -- something like this has
been forever debated on -docs but it sort of fizzled out into
nothingness... perhaps this will stimulate some of us to write a little
more :)
>
> 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.
I have some InputModule docs incoming, so I think they will probably be
a good addition, if there already isn't something there. I'll check out
the new docs ASAP.
> Carsten
Regards,
Tony
RE: [Ann] New Documentation Structure
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
Bertrand Delacretaz wrote:
>
> >> ...So I'd also remove any split between user and developer docs, or
> >> between
> >> basic and advanced topics.
> >>
> > Yes, definitly - this is the main task I want to do in the next weeks.
> > I
> > think with the new structure this is a little bit easier than with the
> > old one. For example, we had a directory under the user docs called
> > concepts containing the docs for the sitemap (user and dev) etc.,,,
>
> I'm also for having less categories in the docs.
>
> Actually I'm wondering about the terms "users" and "developers".
> Everybody who uses Cocoon has to develop something, even if it's just a
> sitemap and some XSLT transforms. Maybe "writing components" would be a
> better term than "developing"?
>
> Also, the new structure made me think again about the "documentation
> tracks" which were discussed a (long) while ago
> (http://wiki.cocoondev.org/Wiki.jsp?page=DocumentationTracksProject). I
> have started working on some examples of what Tracks can be.
>
> Basically, Documentation Tracks are just reading lists which create
> many independent ways of navigating the docs. This should make the
> actual structure of the docs less important. I hope to commit my
> examples tomorrow or Thursday.
>
Great! Thanks.
Carsten
Re: [Ann] New Documentation Structure
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
>> ...So I'd also remove any split between user and developer docs, or
>> between
>> basic and advanced topics.
>>
> Yes, definitly - this is the main task I want to do in the next weeks.
> I
> think with the new structure this is a little bit easier than with the
> old one. For example, we had a directory under the user docs called
> concepts containing the docs for the sitemap (user and dev) etc.,,,
I'm also for having less categories in the docs.
Actually I'm wondering about the terms "users" and "developers".
Everybody who uses Cocoon has to develop something, even if it's just a
sitemap and some XSLT transforms. Maybe "writing components" would be a
better term than "developing"?
Also, the new structure made me think again about the "documentation
tracks" which were discussed a (long) while ago
(http://wiki.cocoondev.org/Wiki.jsp?page=DocumentationTracksProject). I
have started working on some examples of what Tracks can be.
Basically, Documentation Tracks are just reading lists which create
many independent ways of navigating the docs. This should make the
actual structure of the docs less important. I hope to commit my
examples tomorrow or Thursday.
-Bertrand
RE: [Ann] New Documentation Structure
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
Bruno Dumon wrote:
> 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...
>
That's ok - it's not finished :)
> 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.
>
Yes, definitly - this is the main task I want to do in the next weeks. I
think with the new structure this is a little bit easier than with the
old one. For example, we had a directory under the user docs called
concepts containing the docs for the sitemap (user and dev) etc.
> I think this will make the relevant documentation easier to find and
> easier to maintain.
>
Yepp. +1
Carsten
Re: [Ann] New Documentation Structure
Posted by Bruno Dumon <br...@outerthought.org>.
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
RE: [Ann] New Documentation Structure
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
Bertrand Delacretaz wrote:
>
> Le Lundi, 1 sep 2003, à 10:14 Europe/Zurich, Carsten Ziegeler a écrit :
>
> > ...So, in the last days I refactored our documentation a little bit
> > and updated some sections...
>
> less talk, more action, great!
>
:) (yepp, it's sometimes the only working way...)
> > ...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...
>
> At first sight I find your structure much better than the existing one,
> I will try to find some time to have a more detailed look.
>
Great! Thanks!
Carsten
Re: [Ann] New Documentation Structure
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
Le Lundi, 1 sep 2003, à 10:14 Europe/Zurich, Carsten Ziegeler a écrit :
> ...So, in the last days I refactored our documentation a little bit
> and updated some sections...
less talk, more action, great!
> ...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...
At first sight I find your structure much better than the existing one,
I will try to find some time to have a more detailed look.
-Bertrand