Ruby Forum Radiant CMS > [ANN] Summer Reboot Documentation

Hi Guys

We have been in discussion about starting up another effort to write up
Radiant documentation.  I had earlier posted out something like a Table
of Contents that we could use as a preliminary outline.  I've created
this on the wiki as 'Summer Reboot' (in honour of the thread that
started this push again!) and it's online at:
http://wiki.radiantcms.org/Summer_Reboot

I've also created a section on the page called 'Author Abbreviations' -
just put your name there with an abbreviation.  Then, you can use the
abbreviation to claim certain articles as your own :)

If you already have material that could be used, please claim the
article.  If someone has claimed the article already but you have the
same thing written up, please add it in also.  One of us can later
combine the best parts of both to make it completely useful.

Cheers,
Mohit.
6/22/2008 | 4:14 PM.

Well done, Mohit. I've signed up for a few articles. What's the time
horizon on this project - should we aim at having all articles ready
by the end August?

/Casper

Casper Fabricius wrote:
> Well done, Mohit. I've signed up for a few articles. What's the time 
> horizon on this project - should we aim at having all articles ready 
> by the end August?
>
> /Casper
>
That would be great!  Now that Radiant 0.6.7 is out, I hope that the
basic things won't change much for a while.  So, taking 10 weeks out for
this would be great!

I hope that people will also feel free to change the outline to add more
things in.

One last thing - once you've got an article done, just announce it to
the list.  If possible, I'll help to proof read it (not saying that I'm
great at it, just saying that it's good to have another pair of eyes
edit it, if possible).

Cheers,
Mohit.
6/22/2008 | 4:57 PM.

Hate to burst your bubble, but I imagine we'll have 1 or 2 releases
within the next 10 weeks.  I'll be getting back up to speed after my
move to NC, which is in ten days.  If there's anyone in RDU-CH area who
wants to meetup and hack on Radiant on Fridays, be sure to ping me in
the second week of July.

Sean

Sean Cribbs wrote:
> Hate to burst your bubble, but I imagine we'll have 1 or 2 releases 
> within the next 10 weeks.  I'll be getting back up to speed after my 
> move to NC, which is in ten days.  If there's anyone in RDU-CH area 
> who wants to meetup and hack on Radiant on Fridays, be sure to ping me 
> in the second week of July.
>
> Sean

Hahah.. I see!  Let's hope that the changes aren't too big - and that
most things will continue to work as it is!  On the other hand, I'm
happy to see documentation go out of sync if it means that we're getting
a better Radiant! :)

We'll fix the documentation as releases come in!

Cheers,
Mohit.
6/23/2008 | 12:32 AM.

Mohit Sindhwani wrote:
> We have been in discussion about starting up another effort to write up
> Radiant documentation.  I had earlier posted out something like a Table
> of Contents that we could use as a preliminary outline.  I've created
> this on the wiki as 'Summer Reboot' (in honour of the thread that
> started this push again!) and it's online at:
> http://wiki.radiantcms.org/Summer_Reboot

Thanks Mohit, this looks great. I tagged a few articles for myself, 
added a list item for the built-in Archive extension, and added a 
paragraph to the page intro about claiming articles with your initials.

- Dave

David Piehler wrote:
> Thanks Mohit, this looks great. I tagged a few articles for myself, 
> added a list item for the built-in Archive extension, and added a 
> paragraph to the page intro about claiming articles with your initials.
>
> - Dave
>
>   
Thanks Dave, for filling in the gaps for me :)

I love wikis :)

Cheers,
Mohit.
6/23/2008 | 11:46 PM.

On 22 Jun 2008, at 09:17, Mohit Sindhwani wrote:

> Abbreviations' - just put your name there with an abbreviation.   
> Then, you can use the abbreviation to claim certain articles as your  
> own :)

I've just added my name and claimed a few articles. I'd like to write
an introductory piece on Radius tags.

Cheers,
Drew

Andrew Neil wrote:
>> http://wiki.radiantcms.org/Summer_Reboot
>>
>> I've also created a section on the page called 'Author Abbreviations' 
>> - just put your name there with an abbreviation.  Then, you can use 
>> the abbreviation to claim certain articles as your own :)
>
> I've just added my name and claimed a few articles. I'd like to write 
> an introductory piece on Radius tags.
>
> Cheers,
> Drew 

Thanks Drew.  I shall add on to your introductory piece with at least a
bit about how to show dates on articles and to use the other properties
of the 'page' such as author, etc.

Cheers,
Mohit.
6/24/2008 | 5:14 PM.

On Jun 24, 2008, at 2:14 AM, Mohit Sindhwani wrote:

>>> Reboot' (in honour of the thread that started this push again!)  
>>
>> Cheers,
>> Drew
>
> Thanks Drew.  I shall add on to your introductory piece with at  
> least a bit about how to show dates on articles and to use the other  
> properties of the 'page' such as author, etc.


Just signed up for "Creating an extension I – Adding tags".  Since
having to reverse engineer other extensions that implement tags a few
weeks back was no fun.

-Alex
http://beautifulpixel.com

Alex Wayne wrote:
>>>> write up Radiant documentation.  I had earlier posted out something 
>>>
>
> Just signed up for "Creating an extension I – Adding tags".  Since 
> having to reverse engineer other extensions that implement tags a few 
> weeks back was no fun.
>
> -Alex
> http://beautifulpixel.com

Excellent!  This project is really starting to roll now :)

Cheers,
Mohit.
6/25/2008 | 12:19 AM.

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 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, 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

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 ($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.

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$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.

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$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.

Agreed. I would still like it to be a bit like 'article about something'
with a link to a detailed reference, if available.

> 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.

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 $B!H(Bavailable tags$B!I(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 that$B!G(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.

Mohit:

I looked at the existing documentation! Great work. I am willing to fund
some of the activity if that will speed up things. I have a need of such
documentation in September. Feel free to contact if you are interested.

Cheers
Zaheed Haque
zaheed.haque@gmail.com

Zaheed Haque wrote:
> Mohit:
>
> I looked at the existing documentation! Great work. I am willing to fund
> some of the activity if that will speed up things. I have a need of such
> documentation in September. Feel free to contact if you are interested.
>
> Cheers
> Zaheed Haque
> zaheed.haque@gmail.com
>   

Hi Zaheed,

I'm just trying to roughly coordinate the activities relating to the
Summer Reboot documentation.  Thank you for your kind comments about it
- it's been put together so far by the "people" :)

Would money help?  I think this issue is up to the group really.. guys,
what do you feel about Zaheed's offer?

Best wishes
Mohit.