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
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:
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
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
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
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 - http://onghu.com/te 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
Mohit.
_______________________________________________
Radiant mailing list
Post: Radiant@radiantcms.org
Search: http://radiantcms.org/mailing-list/search/
Site: http://lists.radiantcms.org/mailman/listinfo/radiant
_______________________________________________
Radiant mailing list
Post: Radiant@radiantcms.org
Search: http://radiantcms.org/mailing-list/search/
Site: http://lists.radiantcms.org/mailman/listinfo/radiant
_______________________________________________
Radiant mailing list
Post: Radiant@radiantcms.org
Search: http://radiantcms.org/mailing-list/search/
Site: http://lists.radiantcms.org/mailman/listinfo/radiant
