Hi All,
Sorry for being late to the party.
I originally posted to the list on May 2nd about documentation
(“tag documentation feedback”), mentioning among other
things a tag reference. This would have one page per tag, be in a
wiki, and hopefully auto-import the current “available
tags” documentation from the code (would it be possible to
script that?). I’ve added this to the summer reboot wiki page as
an appendix.
Currently the documentation ToC is kind of book-like, in that a user
would start at the start (or a chapter/topic of interest) and read
linearly to the end. I’d also like to suggest we support
reference style, for example the tag reference docs, and problem-
solving style (how-to articles), for example short code example
articles on one topic; how to implement blog-style categories using
<r:aggregate />, how to produce common variants of monthly archive
lists etc.
Currently the docs are a little repetitive or fractured, for example
tag information is spread over four places on the wiki and blog, so we
should also think how to avoid repeating content too much. For
tags I’d propose putting the most detail into a tag reference,
and having eg the “Using the built-in tags” article be an
overview grouped by topic with examples, with links to the tag
reference and how-to articles for more detail. I think that putting
the detail into atomic reference pages will make it easier to keep the
main documentation articles light and quick to read, and help reduce
repetition.
I’m happy to flesh out the tag documentation and add examples,
but someone else will need to write the script to automatically
generate/update wiki pages using the available tags text. If such a
script is impractical I’ll start doing it manually if a tag
reference header page is created.
Some reference for how others do this:
Movable Type: http://www.movabletype.org/documentation/appendices/tags/
Expression Engine: http://expressionengine.com/docs/overview/tags.html
WordPress: http://codex.wordpress.org/Template_Tags
These things would be nice for the tag reference:
* best practice code examples, with expected results
* code coloring in code examples
* links to related tags, how-to articles that use this tag, and
relevant part of tag overview article and other documentation
* a link in the Radiant admin “available tags”
documentation to the more detailed tag reference page on the wiki
Finally it would be great if there was automatic linking of how-to
articles and tag reference pages, ie if a how-to article on monthly
archive lists has a code example with r:children:each, r:find, r:date
and r:header, that it would automatically link to those tag reference
pages, and in turn the how-to article would be linked to on each
relevant tag reference page.
hope that’s of some use
peace - oli
_______________________________________________
Radiant mailing list
Post: [email protected]
Search: http://radiantcms.org/mailing-list/search/
Site: http://lists.radiantcms.org/mailman/listinfo/radiant
