Radiant documentation - summer reboot

Ruby Apps Radiant CMS
1

I’d like to begin my work on extending the Radiant documentation, but
before that I’d like to get an idea of what others on this mailing list
are specifically planning to do so we don’t duplicate effort.

Overall Goals:

  • Make Radiant easier to setup for beginners via better wiki
    documentation
  • Reorganize the wiki so info is easier to find
  • See if we can make the third-party plugins list a main page in the
    radiantcms.org navigation, and call it Extend or something

My Goals:

  • Beginner Docs - simple website setup in 0.6.6

  • Beginner Docs - navigation systems (simple using r:navigation; complex
    using r:if_self and r:if_ancestor_or_self and part=“no-map”)

  • Intermediate Docs - extending the built-in Archive extension to
    maintain News and Events

  • Intermediate Docs - password-protected pages via a simple user
    login/logout system

  • Extensions Docs - how-to setup and bug-fix 0.6.6 extensions Shards,
    WYMeditor, PageAttachments, Reorder, Search, FlickrTags, and Tags

All of the articles specifically for 0.6.6 are already written, I just
need to clean them up and put it into the wiki. The other pieces I still
need to write.

Thoughts? Other people’s goals for the documentation? A plan of action?

  • Dave
2

David P. wrote:

  • See if we can make the third-party plugins list a main page in the
  • Intermediate Docs - extending the built-in Archive extension to
    need to write.

Thoughts? Other people’s goals for the documentation? A plan of action?

  • Dave

Dave, this is great! This is what I was planning with regard to the
documentation.

I am willing to help proof read your documentation and walk through all
the steps (even look at it from the perspective of 0.6.7) if you need
someone to do that. So far, I have a simple ‘Hello World’ article that
talks through creating your simplest first site. I’ve just finished
setting up 0.6.7 for that and have finished capturing screen shots to
augment the original article.

Next, I want to work on this idea of showing how you can solve tasks
using different extensions and what would be a natural flow for setting
them up.

Your flow is quite comparable to what I had proposed earlier, so I’ll
post it here again for reference:

The way I see it, there are 3 sets of documents that are probably
needed:

  1. Radiant for Users: A guide for publishing content using Radiant.
    This would be targeted at end-users and would explain the basics of
    adding pages and using the built-in tags. The idea would be that this
    is the documentation that would form the starting point for someone
    providing a Radiant-based CMS as a solution to their clients. I think a
    lot of the information is probably there in some form in the
    descriptions of the tags. However, it would need to be crystallized in
    the form that a user of a CMS would like to see. I imagine that there
    would be a need also to include a brief guide for designers (though I
    think it would be very brief).

  2. Developing with Radiant: The entry-level guide for people starting to
    develop a solution based on Radiant. This would form the basis on
    teaching a developer how to create a solution around Radiant. Targeted
    primarily at developers who are trying to integrate Radiant and a bunch
    of extensions for their client, this guide would help developers on how
    to install, deploy and use Radiant. It would also look at commonly used
    extensions (PageAttachments, Mailer, basic language support, etc.) and
    how to use them in a solution. It would also look at how to achieve
    most of the common tasks that would be needed in a solution. It would
    also look at answers to the kinds of questions I may have asked in the
    past - how to avoid pages showing up in the menu, how to make search
    pages, how to provide one or more RSS feeds, etc.

  3. Developing for Radiant: This would cover programming for Radiant. I
    imagine that it will include items on creating extensions (with and
    without database usage) and also look at programming tasks related to
    Radiant. It would also cover concepts such as creating page types,
    overriding the title of a page, creating special kind of archive pages,
    and the often asked how to integrate Radiant with Rails, etc.

I’m also working through a more detailed break-up of items with specific
extensions, etc. that would be needed. I think/ suggest that we use a
SQLite database so that we can share it out as a base for the
documentation generators to work with.

I imagine that this documentation should eventually make it into a form
that could be produced as a book with the above 3 as the main sections.
It’s not from the perspective of having a book, but I find a book format
(even a PDF) always gives the feeling that things are stable and solid -
a wiki tends to suggest chaos. Therefore, I would want to head in that
‘eventual’ direction.

I’m happy for others to suggest how they want me to get involved. I
think my best roles would be:

  • Proof reading (I think I’m good at this)
  • Creating ‘idiot-proof’ step-by-step articles with tedious screen shots
  • Co-manage the effort (I have some experience in technical how-to sites

I don’t use Radiant enough to be very familiar with the source (would
love to be, but it won’t be productive in time terms if I worked on it);
so those areas may be better covered by others (at least) initially.

Best wishes
Mohit.

3

I’m experimenting with an idea for help documentation as an extension.
It obviously shouldn’t cover getting up and runnining since you’d only
see it once you are running.

I was going to wait until this was more complete until throwing it out
there to the entire community, but since there’s been so much talk
about documentation, I guess the time is now. It’s still very rough:

http://github.com/saturnflyer/radiant-help

My needs are to provide basic documentation for people currently using
Radiant.
So my thought was to:

  1. hard-code documentation about the core features (so an update
    doesn’t need a migration)
  2. provide a way for extensions to create help documents (either
    through files or the db… currently its in the db)

It has practically no styling or javascript written yet, let alone
actual docs, but the basic idea is there. I’d love some critique/input/
help. Much of the documentation that Mohit and David are discussing
are outside the scope (in my opinion) but not all of it.

It creates a “Help” tab after Layouts and if a particular extension
isn’t registered, it at least gives you info about it by going to
admin/help/ExtensionName

-Jim

4

David,

Sounds like a great plan. One thing that had been mentioned in the BoF
session at RailsConf was screencasts. Anyone willing to make one – of
decent quality and utility of course – can submit it to me or John and
we’ll post it on the main Radiant site.

Sean

5

That’s awesome, Jim. I know it’s something John has talked about adding
into Radiant core. He’s got some good UI ideas about how to make that
most useful – you might talk to him about it.

A Radiant Help system is also the reason why I like Mohit’s breakdown –
but with a slight tweak. If done right, it’s easy to slice off the
content for the help system. By this I’m suggesting:

  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.

So section #1 could be bundled nicely into Radiant and be self
sufficient. Sections #2 & #3 belong on the RadiantCMS site (though we
could put #1 there too). More specifically this might look like:

  1. Using Radiant
    * Working with / Overview of the different objects (pages,
    snippets, layouts)
    * Users and permissions
    * Administrative functions
    * Radius Tags (I’d like to see an overview of how tags work
    plus the descriptions from all the standard tags)
    * Radiant recipes - lots of short examples to help those users
    that learn by example, as well as providing solutions for
    the stickier problems (<r:navigation> stuff, RSS feeds,
    etc.)

  2. Installing Radiant
    * Where to get it
    * Deploying
    * Installing Extensions
    * Finding Extensions and overviews for commonly used ones

  3. Extending Radiant
    * Creating an extension
    * Writing tags
    * Working with the flavor of Radiant (using it’s metaphors,
    etc)

But this list is just to show the organizational concept – Mohit and
Dave have obviously given the specific content more thought than I have.

-Chris

6

Sean C. wrote:

David,

Sounds like a great plan. One thing that had been mentioned in the
BoF session at RailsConf was screencasts. Anyone willing to make one
– of decent quality and utility of course – can submit it to me or
John and we’ll post it on the main Radiant site.

Sean

I don’t yet know how to do screencasts :frowning:
I’m on Windows, so if someone knows something ‘off-the-cuff’ let me know

  • I’ll give it a try. I’ll take a look on Google for screencast tools
    later myself.

Cheers,
Mohit.
6/11/2008 | 11:30 AM.

7

Mohit,

I liked CamStudio on Windows, but I don’t know if it’s easily available
anymore.

Sean

8

Try Jing

I’m not sure if it will work for this purpose, but I’ve used it to
create short demos for various projects.

9

David P. wrote:

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 forgot to add screencasts to that list. Maybe we could host them with
Vimeo or something and link them from the wiki?

A nice end-goal would be some cross-promotion for Radiant with the
Railscasts team. If we could get a “Get Started with Radiant CMS”
episode on Railscasts, I think that would greatly expand the Radiant
audience.

  • Dave
10

Chris P. 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.

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.

This comes back to the question of how to manage all this data. The
ideas stated so far are…

  • expanding on / cleaning up the current wiki
  • using Jim’s radiant-help extension (potentially integrating it into
    the Radiant core in the future)
  • using a mix of both methods

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

One idea is to let extension developers hook into the radiant-help
extension, but also have a wiki page for each known extension. The
radiant-help extension could link to its wiki page as a “Go here for
more information” link. This would allow the developer to maintain the
packaged documentation, but also allow end users like us to expand upon
it. I think this is very important, as it would let us create How-Tos
and provide further examples the extension developer may not have
thought of.

  • Dave
11

David P. wrote:

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

12

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: Fastest Web Hosting Services | Buy High Quality Hosting”

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

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

13

On Jun 11, 2008, at 8:40 PM, Mohit S. wrote:

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

14

Jim G. 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 :stuck_out_tongue: 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.

15

Jim G. wrote:

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

16

Jim G. 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)
      ===
17

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

18

Sean is working on something like that. Ask him about it, he has all
the time in the world :slight_smile:

-Jim
Where’d you get that idea? I actually have too many ideas and too
little time, heh.

Sean

19

On Fri, Jun 13, 2008 at 3:37 PM, Casper F.
[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

20

Mohit S. wrote:

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.

This looks great. The only thing I noticed was missing is a topic on
navigation systems. I say we start with your outline in the wiki and
move ahead from there. We can always adjust the outline as we progress
if we need to.

In the wiki outline, should we mark what topics we would like to work on
so we don’t duplicate effort? I think having multiple people work on the
same topic is fine, but they should probably coordinate their effort.

Silly question – when working with the wiki, how do you create new
pages? Do you just make a link to them and it recognizes a new page has
been made… or something?

I have Friday off from work, and will begin working on wiki content. I
think I’ll start with these topics:

  • navigation systems (simple using r:navigation; complex using r:if_self
    and r:if_ancestor_or_self and part=“no-map”)
  • using some of the common extensions
  • Dave