[Radiant-Docs] Hello and Documentation Ideas

[Mohit Sindhwani]

Hi John

I'm worried about the time commitment myself.  I seem to have found 
myself meandering into helping with documentation for projects somehow 
(my Radiant based TE at Onghu site [1] is an example of just this) and I 
feel that there's a need to make it happen.

That said, I have noticed that you and Sean are indeed the providers of 
most of the documentation.  I'd really like to help but I don't want to 
over-promise-under-deliver which is why I will start small come January 
(as I mentioned earlier) and see what can be added in.

Frankly, given the way Radiant is, you and Sean are much better off 
cranking out the code :-D and us '(temporarily) lesser mortals' are 
better off supporting the documentation, but a bigger effort may be 
necessary.  For example, although I outlined Section 3 below, I don't 
think I'm ready to document that because I don't think I have enough 
working knowledge under the hood to achieve that.  However, every little 
helps, I'm sure.

I wanted to bring up this topic to get a feel of who's on this list and 
what the general feeling is about the documentation.  Once I'm ready to 
start, I shall forward this request to the Radiant users list, too.  I 
think we need an "aggregator" who can push the others for the 
information that is needed and then collate it in the central place.  I 
think the wiki is nice, but it doesn't get updated enough (yet).

Don't hand me the keys yet - I'll ask for them when I'm ready!

Cheers
Mohit.

[1] http://onghu.com/te

John W. Long wrote:
> Mohit,
>
> We've had a couple of people volunteer in the past to work on the 
> documentation, but none of them have been able put serious effort into 
> the project. I'm happy to give you the "keys to the kingdom" if you 
> are interested in working on this. To date, Sean Cribbs and myself 
> seem to be the movers and shakers on the documentation effort, but the 
> time that we can devote to it is minimal. Any help that you can give 
> would be appreciated.
>
> I like what you have outlined below and think that it would be great 
> to see you incorporate some of those ideas into the Radiant Handbook 
> on the wiki.
>
> -- 
> John Long
> http://wiseheartdesign.com
>
> On Dec 1, 2007, at 4:09 AM, Mohit Sindhwani wrote:
>> 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.
>
>