incubator-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <>
Subject each project needs a documentation team
Date Mon, 06 Sep 2004 04:42:06 GMT
(As usual i don't know on which list to raise such
cross-project issues. Should it be community@,
infrastructure, members? Lets start here ...)

David Crossley wrote: 
> It was the first time that either i, or the Forrest PMC,
> ever heard that there were difficulties with the Incubator
> use of Forrest.

I can see how this happens. We are all patient people
and we trust that things will get better soon. Yet our
frustration grows.

Even if one of the Forrest PMC members is on each project
that uses Forrest, resolving the issues is still tricky.
Feedback still does not necessarily flow.

It seems that a crucial part of each Apache project is
a "documentation team". There need to be a few people in
every project that take care to ensure that their documentation
system is as efficient as possible.

This is not particular to using Forrest. Whatever documentation
system is used, the project still needs a few people to oversee
its function, keep the tools up-to-date, ensure that there are
no hurdles with ASF infrastructure or procedures.

Each project making exit from Incubator, and even existing
projects, would all ensure that they have a reliable issue
tracker, and SVN, and mailing lists, etc. However, not as much
attention is placed on the documentation  It seems that many
projects then struggles to produce documentation.

We tried to avoid having a "documentation team" at Cocoon
to ensure that documentation was not ignored by some developers
and just left to those people. That hasn't really made any
difference. Doing documentation is still difficult.

Each project would do their own thing with managing documentation:
some use Anakia, some Forrest, some plain html, some Maven, ...

For all of these systems, people need the choice of editing
local source and locally building and reviewing. Other
people would just edit source documents and commit, then
some automated production would just take over to generate
and stage it.

There would be a common infrastructure that enables staging
and reviewing of documentation before it goes public. We had
a good discussion about this on infrastructure@ recently.
The thread started talking about "forrestbot" and deliberately
covered the issues of staging. There are also many background
threads and proposals like Doco. It all integrates nicely.

However we are having trouble to implement this staging.
Recently there have been promising experiments. See the
infrastructure and incubator mailing lists.

So to summarise, these are some key issues:

* Each project needs at least two documentation facilitator

* Need automated builds of website and staging infrastructure.

* Need improved top-level documentation at /dev/ and /foundation/
to guide each project, and avoid repetitive bottlenecks.

David Crossley

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message