[Radiant] [ANN] Summer Reboot Documentation

[Oli Studholme]

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