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
|