Ruby Forum Radiant CMS > Summer Reboot Update

Hi Everyone

Just a brief update on the Summer Reboot Documentation project.  I just
spent a couple of hours copying and moving stuff to the site from a
couple of places to pull things into the project :)

Brief Update:
* 6 Authors have signed up
* 5 Articles have been provided (in some form or the other)
* A further 11 subjects have been claimed

Link to the main page: http://wiki.radiantcms.org/Summer_Reboot

Looking forward to a few more comments and articles when people get the
time.
Just a reminder: we're targeting end of August 2008.

Cheers,
Mohit.
7/12/2008 | 2:26 AM.

Mohit Sindhwani wrote:
> Just a brief update on the Summer Reboot Documentation project.  I just
> spent a couple of hours copying and moving stuff to the site from a
> couple of places to pull things into the project :)

My schedule hasn't gone according to plan so far this summer, but I hope 
to attack this after I return home from vacation starting Friday the 
25th.

- Dave

Hi All,

Sorry for being late to the party.

I originally posted to the list on May 2nd about documentation
($B!H(Btag documentation feedback$B!I(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 $B!H(Bavailable
tags$B!I(B documentation from the code (would it be possible to
script that?). I$B!G(Bve 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$B!G(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.

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$B!G(Bd propose putting the most detail into a tag
reference, and having eg the $B!H(BUsing the built-in tags$B!I(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.

I$B!G(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 I$B!G(Bll 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 $B!H(Bavailable tags$B!I(B
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$B!G(Bs of some use

peace - oli

On Jul 17, 2008, at 1:32 PM, Oli Studholme wrote:
> 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.

The Help extension does this for you when you install it. Even better,
it gives you documentation for all installed tags and to which page
types they apply.
http://github.com/saturnflyer/radiant-help-extension/tree/master

It does not, however, provide examples beyond what comes with the tag
descriptions.

On Jul 17, 2008, at 1:52 PM, Jim Gay wrote:
> http://github.com/saturnflyer/radiant-help-extension/tree/master
>
> It does not, however, provide examples beyond what comes with the  
> tag descriptions.

I just added 
http://github.com/saturnflyer/radiant-help_use_cases-extension/tree/master

So your extra documentation could be added in as an option (although
this still isn't as non-technical as editing a wiki)

It has almost nothing in it, but I added the ability to extend the
docs for the installed tags in Help 
http://github.com/saturnflyer/radiant-help-extension/commit/d9a4634724465ca115bd0f246b4665917efbe724
(thanks Sean)

This will allow extension developers to add help use cases to their
tags outside of the description in the model.

My priority is to flesh out the features and documentation of Help,
but I'll be adding more info to Help Use Cases as time goes on. If you
are interested in writing docs for each tag, I'll gladly grab it and
put it into Help Use Cases.

-Jim


Jim Gay
http://www.saturnflyer.com

David Piehler wrote:
>
> - Dave
>   

Thanks Dave,

Every drop counts! :)

We still have FIVE weeks to go!

Cheers,
Mohit.
7/22/2008 | 10:14 PM.