Sebastien Arbogast wrote: <snip/>
Moreover this documentation could be written and reviewed in parallel and tight collaboration with the new Cocoon 2.2 documentation effort to make sure that the information is accurate and exact and to keep stuff in sync. And it could be written and reviewed/corrected progressively with the help of users giving feedback about what's missing and what should be removed.
What do you think ?
Why in parallel? Look at http://brutus.apache.org/docs/build/cocoon-2-2/. This build already contains an improved structure that is similar to yours that reflects Cocoon 2.2 in a better way than the current 2.1 docs do (although Upayavira and I discussed this for hours, this doesn't mean that it is carved in stone).
Writing docs for the new documentation system has become as easy as offline-editing can be:
* Download, install and test [WWW] Forrest V0.6. It's a fairly big download,
but easy to install.
* From the src/documentation directory of your local copy of the Cocoon 2.2
code, start forrest run. Note that Run, Forrest, Run! won't work.
* Point your browser to [WWW] http://localhost:8888, you should see the
Cocoon documentation page with the standard Forrest look (similar to the
[WWW] 2.1 website).
* After editing a document under the src/documentation/src/content/xdocs
directory, refresh the page in your browser to see the changes
immediately.(see http://wiki.apache.org/cocoon/22NewDocumentsGeneration)
Every page is an HTML page which makes it very easy to write docs using your favorite HTML editor, no need for clumsy XML editors any more!
Would anyone be interested in helping me to write such a documentation ?
Upayavira, Bertrand and I have already started!
Do you have ideas about technical infrastructure we could use : wiki, mail lists, maybe forums and IRC channel which are ideal for user feedback and easy communication, documentation format (forrest, SVN repository, writing and reviewing process) ?
the new documentation system based on Forrest and plain HTML docs
What about work team organization (I find this very important to avoid stepping over each other's feet and make sure everything is correct and precise, even if it's longer) ?
if you have something to review, open a Bugzilla issue, use the prefix [documentation] for the subject and we can work on it.
What about translations : would some people interested in translating that documentation to other languages as we write it (french ? spanish ?) maybe a few polls on local development communities would be necessary to determine what languages are worth translating to.
the new documentation system also covers this to a certain degree (the docs do but the structure doesn't --> I'm waiting here that future Forrest versions cover multi-language support) but for now we should concentrate on English
What about a common website area to centralize efforts and make the project known to users and potential writers ?
for now this is http://wiki.apache.org/cocoon/22NewDocuments
Maybe it's not necessary to talk about the content in the first place,
to insist on whether or not it would be interesting and if some people
are willing to participate, and what could be the general shape of
such a project...
I'm waiting for your opinions.
FTR, I should precise that right now I'm working on a big project using Cocoon as its core XML server and it's my first project using Cocoon, which implies that -> I won't be able to spend my whole days on this
if others could spend their whole days on writing docs we would be finished for a long time ;-) anyway, you learn most if you regularly work with Cocoon
-> I don't have much knowledge about Cocoon which means that even if I intend to use my newbie aspect to make the documentation accessible and my great interest in Cocoon to make this documentation successful, we would need many interested diverse-skilled people to bring this to realty in a reasonable time (that is before Cocoon 4 at least ;o)
I hope we can welcome you to the new documentation effort started by Upayavira, Bertrand, David and me - I think we already made some big steps forward
- flat doc structure - multi-Forrest-repo customizing (we have to support many doc repos in the future as blocks will become intepend from Cocoon core and so their docs!) - optimized for an online-editor - old docs will be integrated within the next days - although this isn't that visible as dozens of already written docs.
For me it is important that we do all our work on a future-proof, easy to use and extensible fundament (see the above points). By the end of the week we are finished with this base work for the first and can move on to the "actual" work of writing.
--
Reinhard P�tz Independent Consultant, Trainer & (IT)-Coach
{Software Engineering, Open Source, Web Applications, Apache Cocoon}web(log): http://www.poetz.cc --------------------------------------------------------------------
