Hi Oli
Sorry for the late reply. I think there have been a few replies, but
there are a couple of things that I would like to respond to… since I
drew up the first Table of Contents 
Oli S. wrote:
I originally posted to the list on May 2nd about documentation (e$B!He(Btag
documentation feedbacke$B!Ie(B), mentioning among other things a tag
reference. This would have one page per tag, be in a wiki, and
hopefully auto-import the current e$B!He(Bavailable tagse$B!Ie(B documentation from
the code (would it be possible to script that?). Ie$B!Ge(Bve added this to
the summer reboot wiki page as an appendix.
Yes, this should be there - it is currently spread out all over.
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. Ie$B!Ge(Bd 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.
The intent was specifically to keep it book like - so that there was a
first run documentation for Radiant that could actually be read like a
book - cover to cover from basic to advanced. I have always wanted to
fashion this so that it can be made into a PDF book that someone could
put on a shelf if they wanted. Reference style can be added almost
immediately by adding a wiki page that holds it together, so go ahead
and add it in! For what it’s worth, I have tried to capture a few of
those flows - like ‘adding images’ and ‘customizations’, etc.
I also want to make sure that neat tricks and tips are captured so that
we can do a ‘Radiant Recipes’ later - something like Winter Reboot,
perhaps?
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
Ie$B!Ge(Bd propose putting the most detail into a tag reference, and having
eg the e$B!He(BUsing the built-in tagse$B!Ie(B 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.
Agreed. I would still like it to be a bit like ‘article about something’
with a link to a detailed reference, if available.
Ie$B!Ge(Bm 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 Ie$B!Ge(Bll start doing it manually if a tag reference
header page is created.
I think this is a good idea - and I believe that someone has responded
to this.
- 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 e$B!He(Bavailable tagse$B!Ie(B documentation to the
more detailed tag reference page on the wiki
Thanks for the details - these are good!
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.
Any suggestions how we could incorporate this?
hope thate$B!Ge(Bs of some use
It’s of a lot of use! Please continue to contribute to the direction and
content of Summer Reboot 
Cheers,
Mohit.
7/23/2008 | 11:56 PM.
