Re: [Radiant] [ANN] Summer Reboot Documentation
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
Re: [Radiant] [ANN] Summer Reboot Documentation
Andrew Neil wrote: On 22 Jun 2008, at 09:17, Mohit Sindhwani wrote: 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 :) 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. ___ Radiant mailing list Post: Radiant@radiantcms.org Search: http://radiantcms.org/mailing-list/search/ Site: http://lists.radiantcms.org/mailman/listinfo/radiant
Re: [Radiant] [ANN] Summer Reboot Documentation
Alex Wayne wrote: On Jun 24, 2008, at 2:14 AM, Mohit Sindhwani wrote: Andrew Neil wrote: On 22 Jun 2008, at 09:17, Mohit Sindhwani wrote: 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 :) 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. 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. ___ Radiant mailing list Post: Radiant@radiantcms.org Search: http://radiantcms.org/mailing-list/search/ Site: http://lists.radiantcms.org/mailman/listinfo/radiant
[Radiant] [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. ___ Radiant mailing list Post: Radiant@radiantcms.org Search: http://radiantcms.org/mailing-list/search/ Site: http://lists.radiantcms.org/mailman/listinfo/radiant
Re: [Radiant] [ANN] Summer Reboot Documentation
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 On 22/06/2008, at 10:17, Mohit Sindhwani wrote: 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. ___ Radiant mailing list Post: Radiant@radiantcms.org Search: http://radiantcms.org/mailing-list/search/ Site: http://lists.radiantcms.org/mailman/listinfo/radiant ___ Radiant mailing list Post: Radiant@radiantcms.org Search: http://radiantcms.org/mailing-list/search/ Site: http://lists.radiantcms.org/mailman/listinfo/radiant
Re: [Radiant] [ANN] Summer Reboot Documentation
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. ___ Radiant mailing list Post: Radiant@radiantcms.org Search: http://radiantcms.org/mailing-list/search/ Site: http://lists.radiantcms.org/mailman/listinfo/radiant
