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 summer reboot 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 in places, 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: Radiant@radiantcms.org
Search: http://radiantcms.org/mailing-list/search/
Site: http://lists.radiantcms.org/mailman/listinfo/radiant
