Re: [Radiant] Re: Radiant documentation - summer reboot
On Fri, Jun 13, 2008 at 3:37 PM, Casper Fabricius <[EMAIL PROTECTED]> wrote: > Very nice, Mohit. If everyone can approve of this as starting outline for > Radiant documentation, I suggest you put into a page in the wiki. Then we > can add our names to the sections we would to like write, and add further > sections we think is needed. BTW, I'm slowly working on a testing extensions tutorial with rspec and scenarios. I'd be happy to add it to this doc. Cheers, Marty ___ Radiant mailing list Post: Radiant@radiantcms.org Search: http://radiantcms.org/mailing-list/search/ Site: http://lists.radiantcms.org/mailman/listinfo/radiant
Re: [Radiant] Re: Radiant documentation - summer reboot
Very nice, Mohit. If everyone can approve of this as starting outline for Radiant documentation, I suggest you put into a page in the wiki. Then we can add our names to the sections we would to like write, and add further sections we think is needed. Cheers, Casper On 13/06/2008, at 20:18, Mohit Sindhwani wrote: Jim Gay wrote: So, here's what I'm going to try to do. I made a list of topics that I would like to see as part of the documentation, roughly organized by topic. When I get back home from work tonight, I'll try to type that in and email it out just to share my ideas with you. I know that there will be many things that could be debated in that list but it may serve as a reference (even if it is trashed). That would be awesome. It'll at least help me write the docs for radiant-help to see how others want it organized. Hi Guys Sorry for the delay in pushing this out. This is roughly the first draft of the plan that I had. This is not split up into the sections that I had mentioned. I think some of these can be mixed and matched into the different sections. In general, this targets a person who is starting with Radiant but is actually a developer. I'm sure there's plenty more that can/ should go in, but I'm just passing this as a starting point. Cheers, Mohit. 6/14/2008 | 2:17 AM. === RADIANT DOCUMENTATION === 1. Installation & First Steps * Downloading & Installing Radiant - gem, svn, git, edge * Getting Started I - "Hello world" with Radiant * Planning your site (what are layouts, snippets, pages, page parts) * Getting Started II - Improved Stylesheets - Using Layouts & Snippets - Filters & Using Textile * Themes - Why are there no themes for Radiant? - Using the 'Hemingway' Radiant them? - Who does themes? (Radiant pros) * Introduction to the Admin UI and Users * Installing your first extension (PageAttachments?) * Improved Stylesheet/ Script management (SnS) * Deploying your first site (general tips with guidance to specific host articles) 2. Common Tasks & Extensions * Migrating from other sites - Wordpress, Mephisto, etc. * Understanding tags & Radius * Getting Started III - Meta tags & Date of publishing * PageAttachments - Installations, providing downloads and linking to images/ thumbnails * Beyond HTML - providing a simple RSS feed for your site * Customizations - Time zone * Gallery - Image galleries * WYSIWIG Editors - WymEditor, FckEditor * Sitemap * Import/ Export * Using Radiant as a blog * Search Extension 3. Writing your Own Extension * Creating an extension I - Adding tags (and some useful tags) * Creating an extension II - Adding a tab in Admin UI (and what is shards?) * Creating an extension III - Modifying the Page UI from an extension 4. Additional Configurations & Advanced Admin * Previewing Radiant Pages (developer viewing) * Multi-site Extension (why and how) * Customizations II - Admin title, etc. * Skinning the Admin UI * Installing to a sub-domain * Installing to a sub-directory * Dealing with Caching 5. Commonly Used Extensions * Copy and Move * Reorder * Featured Pages * Mailer * Syntax Highlighter * Calendar/ Events * RSS Aggregator * Comments * Multiple RSS feeds from the content * Scheduler Extension * Newsletter 6. Advanced Topics (few solutions yet) * Versioning the content * Tagging & Rating Content * Multiple Languages * Migrating from SQLite to MySQL/ other database * Staging Extension (and ideas on how to do it) * Protecting the data * Setting up user access/ passwords * Integrating with Rails * Providing end-user help (radiant_help) === ___ 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] Re: Radiant documentation - summer reboot
Jim Gay wrote: So, here's what I'm going to try to do. I made a list of topics that I would like to see as part of the documentation, roughly organized by topic. When I get back home from work tonight, I'll try to type that in and email it out just to share my ideas with you. I know that there will be many things that could be debated in that list but it may serve as a reference (even if it is trashed). That would be awesome. It'll at least help me write the docs for radiant-help to see how others want it organized. Hi Guys Sorry for the delay in pushing this out. This is roughly the first draft of the plan that I had. This is not split up into the sections that I had mentioned. I think some of these can be mixed and matched into the different sections. In general, this targets a person who is starting with Radiant but is actually a developer. I'm sure there's plenty more that can/ should go in, but I'm just passing this as a starting point. Cheers, Mohit. 6/14/2008 | 2:17 AM. === RADIANT DOCUMENTATION === 1. Installation & First Steps * Downloading & Installing Radiant - gem, svn, git, edge * Getting Started I - "Hello world" with Radiant * Planning your site (what are layouts, snippets, pages, page parts) * Getting Started II - Improved Stylesheets - Using Layouts & Snippets - Filters & Using Textile * Themes - Why are there no themes for Radiant? - Using the 'Hemingway' Radiant them? - Who does themes? (Radiant pros) * Introduction to the Admin UI and Users * Installing your first extension (PageAttachments?) * Improved Stylesheet/ Script management (SnS) * Deploying your first site (general tips with guidance to specific host articles) 2. Common Tasks & Extensions * Migrating from other sites - Wordpress, Mephisto, etc. * Understanding tags & Radius * Getting Started III - Meta tags & Date of publishing * PageAttachments - Installations, providing downloads and linking to images/ thumbnails * Beyond HTML - providing a simple RSS feed for your site * Customizations - Time zone * Gallery - Image galleries * WYSIWIG Editors - WymEditor, FckEditor * Sitemap * Import/ Export * Using Radiant as a blog * Search Extension 3. Writing your Own Extension * Creating an extension I - Adding tags (and some useful tags) * Creating an extension II - Adding a tab in Admin UI (and what is shards?) * Creating an extension III - Modifying the Page UI from an extension 4. Additional Configurations & Advanced Admin * Previewing Radiant Pages (developer viewing) * Multi-site Extension (why and how) * Customizations II - Admin title, etc. * Skinning the Admin UI * Installing to a sub-domain * Installing to a sub-directory * Dealing with Caching 5. Commonly Used Extensions * Copy and Move * Reorder * Featured Pages * Mailer * Syntax Highlighter * Calendar/ Events * RSS Aggregator * Comments * Multiple RSS feeds from the content * Scheduler Extension * Newsletter 6. Advanced Topics (few solutions yet) * Versioning the content * Tagging & Rating Content * Multiple Languages * Migrating from SQLite to MySQL/ other database * Staging Extension (and ideas on how to do it) * Protecting the data * Setting up user access/ passwords * Integrating with Rails * Providing end-user help (radiant_help) === ___ Radiant mailing list Post: Radiant@radiantcms.org Search: http://radiantcms.org/mailing-list/search/ Site: http://lists.radiantcms.org/mailman/listinfo/radiant
Re: [Radiant] Re: Radiant documentation - summer reboot
Jim Gay wrote: On Jun 11, 2008, at 8:40 PM, Mohit Sindhwani wrote: 2. radiant internal method for extension developers to be able to create documentation for their parts [Sean] I think Sean will clarify too, but radiant-help currently allows you to create documentation to display in the admin interface about your extensions. Sean is working an extension registry which will have some very cool features if he can get them all done (but I'll leave the details to him). At one point this was the "accents" application in Radiant trunk, but judging by a quick glance at that code, he's building something else somewhere else. FYI It's in a local branch that I started at the code-drive that I haven't pushed to github. Sean ___ Radiant mailing list Post: Radiant@radiantcms.org Search: http://radiantcms.org/mailing-list/search/ Site: http://lists.radiantcms.org/mailman/listinfo/radiant
Re: [Radiant] Re: Radiant documentation - summer reboot
Sean is working on something like that. Ask him about it, he has all the time in the world :) -Jim Where'd you get that idea? I actually have too many ideas and too little time, heh. Sean ___ Radiant mailing list Post: Radiant@radiantcms.org Search: http://radiantcms.org/mailing-list/search/ Site: http://lists.radiantcms.org/mailman/listinfo/radiant
Re: [Radiant] Re: Radiant documentation - summer reboot
On Jun 11, 2008, at 8:40 PM, Mohit Sindhwani wrote: 2. radiant internal method for extension developers to be able to create documentation for their parts [Sean] I think Sean will clarify too, but radiant-help currently allows you to create documentation to display in the admin interface about your extensions. Sean is working an extension registry which will have some very cool features if he can get them all done (but I'll leave the details to him). At one point this was the "accents" application in Radiant trunk, but judging by a quick glance at that code, he's building something else somewhere else. So, here's what I'm going to try to do. I made a list of topics that I would like to see as part of the documentation, roughly organized by topic. When I get back home from work tonight, I'll try to type that in and email it out just to share my ideas with you. I know that there will be many things that could be debated in that list but it may serve as a reference (even if it is trashed). That would be awesome. It'll at least help me write the docs for radiant-help to see how others want it organized. ___ Radiant mailing list Post: Radiant@radiantcms.org Search: http://radiantcms.org/mailing-list/search/ Site: http://lists.radiantcms.org/mailman/listinfo/radiant
Re: [Radiant] Re: Radiant documentation - summer reboot
Jim Gay wrote: I really like the idea of extension writers being able to extend the help system (Section #1) -- say adding documentation for their tags or explaining how to use their UI elements, or adding context sensitive help to their UI elements. Then you could crank out a PDF and have it be a complete user's guide -- extensions and all. I plan to make radiant-help easily printable, but Mohit's idea for a book is a good one, although to me seems like it would be a more in-depth look at Radiant and far too long for a help system. I think my idea of the book needs to be revised slightly. [1] We may end up targeting Section #1 as being online [about 90% of it using radiant_help perhaps) and being available completely offline in the form of a printed document. This would be customized by the system developer and provided to the end client. [2] We'd have printable documentation (in the form of a book) which is about 'Radiant' - this would include all 3 sections and would be available for people developing with/ for Radiant. Guys, some of the ideas in the past few emails are fantastic. I think there are 4 parallel tracks now: 1. radiant_help - for providing online help/ documentation [Jim] 2. radiant internal method for extension developers to be able to create documentation for their parts [Sean] 3. creating content for all the parts 4. setting up wiki/ screencast, etc. for people to use while creating #3. I know that there are people who will be naturally attracted to #1 and #2 since it's a bit more 'technical' and a bit less 'documentation' oriented :P but I think my original intent was to work more with #3 - I feel if the base content is there, it can be massaged into the final form, into the final sections, etc. So, here's what I'm going to try to do. I made a list of topics that I would like to see as part of the documentation, roughly organized by topic. When I get back home from work tonight, I'll try to type that in and email it out just to share my ideas with you. I know that there will be many things that could be debated in that list but it may serve as a reference (even if it is trashed). Cheers, Mohit. 6/12/2008 | 8:36 AM. ___ Radiant mailing list Post: Radiant@radiantcms.org Search: http://radiantcms.org/mailing-list/search/ Site: http://lists.radiantcms.org/mailman/listinfo/radiant
Re: [Radiant] Re: Radiant documentation - summer reboot
I really like the idea of extension writers being able to extend the help system (Section #1) -- say adding documentation for their tags or explaining how to use their UI elements, or adding context sensitive help to their UI elements. Then you could crank out a PDF and have it be a complete user's guide -- extensions and all. I plan to make radiant-help easily printable, but Mohit's idea for a book is a good one, although to me seems like it would be a more in- depth look at Radiant and far too long for a help system. radiant-help allows you to provide whatever help information you want, but it assumes that its for an extension. It'll also display details for any loaded constant if it has version, url, and/or description. If for example you have radiant-help installed and go to admin/help/ Radiant, you'll get: "It appears that do you have Radiant installed, but I can't find any documentation for you. Sorry." I thought that would be an interesting way to auto-discover docs about something in the core... but I haven't done more than that. Or if you go to an extension that you have installed but that hasn't registered any help admin/help/TestExtension "No help information is provided at this time. TestExtension version is: 1.0 TestExtension description is: Describe your extension here TestExtension url is: http://yourwebsite.com/test"; What I'd also like to do is add shards-like regions to the basic help info to allow people to add in their own information to the basic docs before or after certain parts. I'm hoping that would give me a way to provide client specific information. Aside from that, I think it makes sense to include role based docs, but I haven't tackled that yet. I've written 2 other apps that included an inline help system where I tracked a needs_help field on the User and conditionally displayed help in the interface. I want to be able to provide something like that as well. I don't want to hijack this thread though, since it wasn't radiant- help centric. My basic goal is to provide info for those using Radiant (including admin and developers), not necessarily for those developing parts for it (such as how to integrate with other apps, or how to write your own extension, etc). It would be *very* nice, however, for RadiantCMS.org to offer a place for extension developers to more formally show off their wares and encourage a standardized style to the documentation. This would make it easier for users to find extensions and learn about them (since their documentation would follow a standard the user would quickly learn). I'm not sure that you'd offer a lot of space for extension developers but perhaps just a page like: http://agilewebdevelopment.com/plugins Sean is working on something like that. Ask him about it, he has all the time in the world :) -Jim PS. For anyone that missed it, I'm talking about http://github.com/saturnflyer/radiant-help/tree/master And I'd love some help setting it up. ___ Radiant mailing list Post: Radiant@radiantcms.org Search: http://radiantcms.org/mailing-list/search/ Site: http://lists.radiantcms.org/mailman/listinfo/radiant
Re: [Radiant] Re: Radiant documentation - summer reboot
David Piehler wrote: Chris Parrish wrote: 1. Using Radiant - This section covers all the stuff users do from within the Radiant Admin Interface 2. Installing Radiant - This section covers getting the source (including extensions) and getting it to run 3. Extending Radiant - This section covers writing extensions. These three focus areas sound good. We should expand #2 to include Mohit's idea of "creating a solution around Radiant" with mini How-Tos for accomplishing goals via specific extensions. Dave, that's exactly what I had in mind. Anything that helps people set up Radiant, install extensions, or otherwise find and integrate the pieces for their Radiant/Rails application goes here. The exceptions would be: * Anything that deals with using the Radiant UI (building site navigation, complex layouts, etc) goes in section #1 * Anything that entails them writing their own code, goes in section #3 Mohit's idea of printable documentation for the end user who will be updating Pages, Snippets, and Layouts is interesting. My company currently gives all our Radiant users a User Guide created for their specific Radiant install. We make these using Adobe InDesign, so they are really nice looking but are time consuming to update. If we could figure out a way to make printable user guides via some common method (maybe using a demo Generic Radiant Website), that would be great. I, too, like the printed documentation. However, I think that this applies only to Section #1. This would also be the only section included in a Radiant help system (and I'm sure its the only part you'd hand out to your users). If Section #1 were bundled with Radiant as a help system, I don't see why we couldn't combine some printable HTML/CSS or PDF templates and use a Rails gem/plugin/whatever like: http://wiki.rubyonrails.org/rails/pages/Rfpdf http://maruku.rubyforge.org/ http://wiki.rubyonrails.com/rails/pages/HTMLDOC http://railspdfplugin.rubyforge.org/wiki/wiki.pl That way you could use a Rake task to spit out the help as PDF during install/upgrade then link to it from the Radiant Help system. Sections #2 & #3 are IT and Programmer focused and should just stay on the Wiki (my opinion, anyway). I think the core goals for the documentation are... * easily update-able * allow for screenshots inline with text and code samples * clean printouts * packaged with Radiant itself and each extension that wants to hook into it * expandable by people not involved with maintenance of the extension itself I really like the idea of extension writers being able to extend the help system (Section #1) -- say adding documentation for their tags or explaining how to use their UI elements, or adding context sensitive help to their UI elements. Then you could crank out a PDF and have it be a complete user's guide -- extensions and all. When it comes to section #2, however, I think the Radiant Wiki should point out a few extensions, perhaps, but ultimately lead users back to the extension developer's documentation. It would be *very* nice, however, for RadiantCMS.org to offer a place for extension developers to more formally show off their wares and encourage a standardized style to the documentation. This would make it easier for users to find extensions and learn about them (since their documentation would follow a standard the user would quickly learn). I'm not sure that you'd offer a lot of space for extension developers but perhaps just a page like: http://agilewebdevelopment.com/plugins -Chris ___ Radiant mailing list Post: Radiant@radiantcms.org Search: http://radiantcms.org/mailing-list/search/ Site: http://lists.radiantcms.org/mailman/listinfo/radiant
