[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 :slight_smile:

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 F. 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 C. 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! :slight_smile:

We’ll fix the documentation as releases come in!

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

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

On 22 Jun 2008, at 09:17, Mohit S. wrote:

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

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

Cheers,
Drew

David P. 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 :slight_smile:

I love wikis :slight_smile:

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

Andrew N. 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 :slight_smile:

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

Hi All,

Sorry for being late to the party.

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.

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.

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.

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.

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 e$B!He(Bavailable tagse$B!Ie(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 thate$B!Ge(Bs of some use

peace - oli

Alex W. 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 :slight_smile:

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

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
[email protected]

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

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? :stuck_out_tongue:

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

Cheers,
Mohit.
7/23/2008 | 11:56 PM.

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
[email protected]

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” :slight_smile:

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.

This forum is not affiliated to the Ruby language, Ruby on Rails framework, nor any Ruby applications discussed here.

| Privacy Policy | Terms of Service | Remote Ruby Jobs