(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 people. * 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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
