Bertrand Delacretaz wrote:
Recent discussions here, along with David's "ASF-wide documentation staging and publishing" post to infrastructure@ made me think about this, in a "there must be an easier way" mood. I'm not ready to discuss this on infrastructure@ though, it feels safer here ATM ;-)
The apparently realistic possibility of having a live instance of Cocoon could make it much easier to handle our docs and website, and unless I'm overlooking something important the concept described below seems really simple to implement. So I cannot refrain from sharing this idea, although I have no code to back it up yet...
GOALS
G1. Generate our docs and website dynamically, directly from the SVN repository accessed over http
G2. Give access to older versions of the docs using standard SVN mechanisms (tags etc)
G3. Index the latest version of the docs, including structured fields (keywords, target audience, components mentioned, etc), to implement "prepared queries" (as links, simply) to improve our docs' accessibility
TOOLS / TECHNIQUES T1. Get content from SVN, editing is considered a separate problem
T2. Build an index with Lucene, triggered via SVN post-commit hooks, uses a live Cocoon instance to generate an easy to index XML document for Lucene. Include metadata fields as mentioned in G2 above, generated from (enhanced as compared to now) document content
T3. Generate pages using a live Cocoon instance, maybe Forrest. SVN tags "pass through" the URLs to give access to older releases of the docs.
T4. Use queries like "find all documents which talk about sitemap matchers" to build navigation pages semi-automatically.
T5. Put mod_cache in front to minimize server load (HTTP POST can be used to invalidate pages if quick updates are needed to check edits).
WDYT?
The thing you seem to have missed is the staging process. If I have written an xdoc, I want to see that as HTML, on a staging server, before I actually publish it. After all, the XML might not even be valid, or there might be mistakes. I need to be able to see the page on the site before I publish it.
Thoughts?
Regards,
Upayavira
