Revised 2009-05-21 to reflect changes made.
Basically, for the short term, I've revised the following four pages:
- http://www.stringtemplate.org
- http://www.antlr.org/wiki/display/ST/StringTemplate+Wiki+Home
- wiki StringTemplate Documentation page
- TOCs are included using wiki "include" from master TOCs
- I more explicitly identified a set of documents as the Users' Guide (these were already the set of children under this wiki page, minus the release notes)
- Credits and Related blocks inserted by "include"
- wiki StringTemplate 3.0 Printable (all-in-one) page
- Content sections assembled using wiki include, as the existing page does.*** But revise these includes to include currently missing pages
- Within-page TOC*** Manually maintained as in the existing page. Revise to incorporate subheadings, and include missing pages
- Individual-topics TOC is included using wiki "include" from master TOC*** Plus links to other documents
- Credits and Related blocks inserted by "include"
I suggest making further changes:
- StringTemplate.org home page:
- just add a link to StringTemplate wiki home, rather than just to the main Docs page
- StringTemplate 3 Wiki Home:
- TOC is included using wiki "include" from master TOC -- but how much and in how much detail
Benefits
- Reinstate usefulness of all-in-one "Printable docs" page
- Maintain an educative User Guide TOC in only one place, (albeit manually due to wiki shortcomings, discussed below)
- Relatively tractable maintenance of the TOCs and includes (even given the wiki in-browser editor).
Longer term
I think grouping pages more clearly and consistently will help make maintenance of TOCs more tractable.
Currently, "the authoritative list of documentation: is split between StringTemplate.org home page, wiki: StringTemplate home page and wiki StringTemplate Documentation page, none of them having the comprehensive list. This could be thought through much better, providing clearer way-finding for users, and easier maintenance.
Terence suggests brain-storming at the ANTLR conference in June... sounds good.
Details
1. User Guide as a concept: There was some vagueness about what was included in various places under the heading "StringTemplate documentation". I think the distinction that's worth making is "StringTemplate Users' Guide" vs other docs that are more tutorial or introductory, concern transitory issues like release notes or that focus on obscure technical issues. Fair enough, so I advocate picking a term like "Users' Guide" and going with it.
2. Maintenance of all-in-one doc: In connection with the all-in-one Printable Documentation page (ie: "Users' Guide on one page"). This was already built using the include macro, but had gotten out-of-step with the actual collection of User-Guide-y pages. I brought this in step, and added a TOC table which also shows the individual-page articles beside, for easy comparison.
3. See also More notes below:
Note: The specific choices of page-ordering, and inclusion (or not) in the all-in-one page could stand debate and refinement. The mockups are just to demo the concept. In particular, I'm not sure what the wiki StringTemplate Documentation page adds that couldn't be on the ST wiki home page... but that's for later debate.