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.


Jim Gay wrote:
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:

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


On Jun 10, 2008, at 12:19 PM, Mohit Sindhwani wrote:

David Piehler wrote:
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
* Reorganize the wiki so info is easier to find
* See if we can make the third-party plugins list a main page in the 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

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 - is based on my main work)

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

Radiant mailing list

Radiant mailing list

Radiant mailing list

Reply via email to