Jorg Heymans wrote:
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}
As we discussed at the hackathon, I think both are concerns that interrelate, and effort can be applied separately to either.
As it is, we have a complex system that few people know how to operate. I've written docs, but I've never deployed them to the site. This acts as a dis-incentive to existing and potential documentation writers.
Other than that, we have a xdocs system that does work, and a wiki that works. We can use right now to write better docs. We just need to make the effort.
So I think both are valid - documentation quality and publication tools.
Regards, Upayavira
