cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefano Mazzocchi <stef...@apache.org>
Subject Re: Offer to help on Cocoon documentation
Date Mon, 29 May 2000 20:06:32 GMT
[copied on the list to let everyone know]

pbinkley@library.ualberta.ca wrote:
> 
> Hi,
> 
> I've been working with Cocoon (in a test environment) for a couple of
> months, and I'm very excited about its prospects. I'd like to contribute to
> the project if I can. 

Hey, that's great!

> I don't have the technical skills to help with the
> code, but I think I see a need I can help with. The online documentation is
> sometimes difficult to understand, I think because parts of it were written
> by someone whose first language is not English (have I guessed right?) 

Yep, I'm italian and English is not my native language.

> There
> are lots of minor grammatical errors, and a few more significant problems
> that make the meaning obscure. Since people always respond better to a text
> that looks more "finished", I think it would be worthwhile to fix these
> little errors, even the cosmetic ones. I have a humanities Ph.D. (medieval
> history, God help me), I've written for publication, and I have experience
> in editing English texts written by non-native-speakers for publication. I
> would be very happy to take on some of the editing work, and perhaps free up
> some of the developers' time for more important things.

You are our saviour, man! I've always wanted somebody like you around,
it would make the project _so_ much better and nicer....
 
> If this makes sense to you, let me know how we can make this work.

Totally!

Ok, since many people asked to help in the documentation, I'll explain
how the documentation process goes as far as Cocoon1 is concerned:

1) document originals are written in XML using a simple HTML-like DTD we
designed. All the documents are found in the /xdocs/ directory and the
DTDs are found in the /xdocs/DTD directory.

2) to generate the documentation simply type "./build.sh docs" or
".\build.bat docs" at the command line. HTML documents will be generated
in the /build/docs directory.

3) feel free to modify, add, change, comment, expand, cleanup, fix, or
otherwise improve the documentation you find in the xdocs directory. Do
_NOT_ modify or send documentation in HTML since this won't be accepted.

4) if you want to add a page to the documentation, you have to modify
"docs-book.xml" and "site-book.xml" files, which represent the
micro-sitemap for documentation. (learn by example, the book schema is
very easy)

5) provide us with patches or complete documents. Please, run them once
in the build process to validate them and make sure the markup is
correct (this will guarantee the stylesheets won't mess up with them,
XML validation is awesome when used correctly!)

So far so good.

For the Cocoon2 project, I would love to move all the documentation into
Docbook, but don't worry, this can be easily done with XSLT and the
original DTD can be used if you think it's simpler. Anyway, do take a
look at the DocBook DTD to find out the potentials.

Thanks in advance for your help and don't feel pushed: anything help
you'll be able to provide will make us happy.

-- 
Stefano Mazzocchi      One must still have chaos in oneself to be
                          able to give birth to a dancing star.
<stefano@apache.org>                             Friedrich Nietzsche
--------------------------------------------------------------------
 Missed us in Orlando? Make it up with ApacheCON Europe in London!
------------------------- http://ApacheCon.Com ---------------------



Mime
View raw message