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 :P
Oli Studholme wrote: > 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. 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. 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. 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? :P > 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. Agreed. I would still like it to be a bit like 'article about something' with a link to a detailed reference, if available. > 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. I think this is a good idea - and I believe that someone has responded to this. > 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 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 that’s 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. _______________________________________________ Radiant mailing list Post: Radiant@radiantcms.org Search: http://radiantcms.org/mailing-list/search/ Site: http://lists.radiantcms.org/mailman/listinfo/radiant
