Bertrand Delacretaz wrote:
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?
I pondered long (well, about 5 minutes) and hard on how to correctly phrase the first two things that came to my mind when I read your proposal - so here goes :
1)Does all this actually make the documentation any better?
2)Should any effort towards documentation ATM go into improving its *quality* or improving its {searchability|updateability|scaleability|auto-generateability}
WDYT?
Jorg
