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
