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