On Tue, Dec 27, 2005 at 04:17:37PM +0100, Thomas Dudziak wrote: > since I'm rather new to this, I don't have a deep understanding of the > problems you're trying to solve.
None is needed, the problem is very simple. > However, to my naive understanding its two things: > > * make the process of documenting incubated projects easier for their > community > * make the process of publishing this documentation easier (and more > stable) for infra/incubator people Actually its not for the incubated projects, just for the incubator documentation and website itself. Each and every incubated project decides what they want to do. > Now I don't really know about the problems that you have with Forrest > regarding the second point - it works for the projects that I work in, > but then again we probably have fewer/simpler requirements. It would > be nice if you could perhaps provide some details, e.g. regarding > SVN-based publishing ? Err, I would suggest you please go and read the [EMAIL PROTECTED] archives. That's basically a "FAQ" at this point. You may also wish to go and look for some posts by me over the last few years to the forrest mailing lists, or to the avalon mailing lists with the added keyword of "forrest". > Anyway, I think there are several possible things that could be done > to deal with this (in the line of "eating your own dog food"), aside > from implementing a new tool: > > * Get Cocoon/Forrest developers to help in the Incubator. We have a few actually. David Crossley is our "manual forrestbot" but it doesn't scale. This is a bad idea. Everybody who knows SVN and how to type in commands on a console should be able to manage the documentation process end-to-end. > * Simplify Forrest for 'admins'. Yes its possible but it doesn't solve everything (its still going to be big and complex and bloated and overkill no matter how pretty the user interface is). > * Simplify documentation writing for end users. > > Actually, I think this is quite an important point. Writing a new tool > probably means yet another XML (or some other format) to learn, which > is Not A Good Thing (tm). IMHO it would be better to get away from XML > completely and pursue simpler solutions. +1. > One such thing might be the OpenOffice plugin that generates Forrest > files, which would help new projects a lot in writing/converting > existing documentation. I will assert OpenOffice is big and bloated and overkill too and not simple at all. I like vi and subethaedit. And HTML. > Another thing might be abandoning Forrest altogether for Incubation > docs in favor of, for instance, a protected Wiki that only the project > developers (and mentors, PMCs, ...) have write access to. And there's > is probably a not-too-complicated technical way to convert this later > on to Maven or Forrest format once the project comes out of > incubation. See Alex Karasulu's post to site-dev a while back for an approach where we could have an admin-protected Confluence to serve as an editing interface for xdoc. There's a lot of ways to do things. > Anyway, I hope you don't mind me making a case for using this as an > opportunity to make Forrest better instead of abandoning it. Well, basically I do. I've spent several years (ever since Avalon became the first forrest user outside the xml.a.o group) working with forrest, helping it to improve and try and help to turn it into something that satisfies our simple use case, but its just not a good idea to keep going down that path. I've read through about 9 months of discussion on the site-dev list where basically the same discussion took place over and over again which was very frustrating (or so it seems) for all the participants. Nothing is ever going to get done if we keep having the same discussion over and over again. There is such a thing as "trying too hard" to get "full consensus" on a topic that is "too vague". DavidC's site management proposal from so long ago and each and every proposal after that has something along the line of "Projects can use various documentation tools: Anakia, Forrest, Maven, raw html, etc. Each system would have its own ways to report build problems to the committer (e.g. xml validation, broken links, content and spelling errors, configuration errors)." for a good reason. "There is more than one way to do it" and this is going to be Yet Another Way. I don't want to spend more time helping to improve Forrest or discussing the relative merits of a variety of solutions. I have an itch to scratch and I want to build a little piece of software to scratch it, in a way that is compatible with all the goals and needs of the ASF, the Infrastructure Team, the Incubator, the Gump project, and hopefully a few other projects. But I don't want to concern myself with the needs of the Forrest community right now as part of this effort, that's making it too hard to get anything done. cheers, LSD --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
