Notes on StringTemplate documentation

Page for gathering ad hoc notes on StringTemplate docs.

Users' Guide vs "The rest"

There's already an impetus to present users/readers with a selection of the full wiki pages as a coherent subset which provides a "comprehensive foundation understanding" for all features of StringTemplate that a user would normally need. This would distinguish it from other docs which might be:

• More technical or exhaustively detailed: APIs/javadoc, discussion of particular technical nuance
• Specialized for particular audience:  Eg: notes relative to particular language version
• Time-sensitive: Eg: Release notes
• Less organized: Eg; FAQs

Currently, such "user-guide-esque" pages are children of page StringTemplate Documentation, though they are unsorted, and thus, if listed by the children macro (as on the StringTemplate wiki home page), appear alphabetically. Elsewhere (such as on the StringTemplate Documentation page itself), the same pages are shown in manually-maintained table-of-contents listing in a more coherent order, but are intermingled with other pages, (for example in the Release Notes).

Bottom line: It would be helpful to achieve better clarity on major categories of pages, so that they could be presented by these groupings consistently. I advocate establishing the notion of "Users' Guide" more prominently and consistently.

Page Organization features and process

In this other page, I describe what I understand to be the extents and limitations of Confluence wiki's features for organizing pages, and for displaying that structure.

Confluence lacks fully-fledged tools for managing the structure and relationships of a collection of pages as a coherent whole, so we are obliged to work with a more limited set of features.

Implications:

• Users' Guide TOC/page map: Maintain manually: An informative/educative TOC or page map, at least for a Users' Guide, cannot be arrived at by either the children macro (for individual topic pages), nor by the toc macro applied to an all-in-one page (composed using includes). Consequently, these TOC-type stuctures have to be maintained by hand.
  • Especially for the individual-topic-pages, these should be a single master Users' Guide TOC page that can be included where it's needed.
    • There could be other master TOC pages that provide manually-organized TOCs for content beyond just Users' Guide.
    • In theory, the master Users' Guide TOC page could be used to automate generation of the all-in-one page's includes and TOC... however writing and integrating that would require more than regular wiki-member permissions.  At the least, the master TOC can form a visual guide for the all-in-one page's includes and TOC.
• children macro's "all" option shows too much: If there are going to be pages whose only purpose is to support other pages via "include", then these will appear in listings by the children macro with the "all" option.  Unfortunately there appears to be no way to filter out unwanted pages. So, where "all" was used needs to be replaced with a more selective set of smaller children listings, showing specific sub-branches.
  • Alphabetical: Note the critique that the childen macro will likely show pages in alphabetical order, so is not a suitable tool for groups of child pages which should be ordered some other way.
  • Possible workaround for "all": Seems to be possible to put pages outside the hierarchy that's included in "all"!