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: [email protected]
Search: http://radiantcms.org/mailing-list/search/
Site: http://lists.radiantcms.org/mailman/listinfo/radiant
_______________________________________________
Radiant mailing list
Post: [email protected]
Search: http://radiantcms.org/mailing-list/search/
Site: http://lists.radiantcms.org/mailman/listinfo/radiant
