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 :)

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

Reply via email to