Oh, that would be very nice!

Right now there is an example at camping.rubyforge.org showing a blog
skeleton (with controllers, models and views). It might be better to rather
have a tiny, fully functional one (to get the feel of Camping), and a link
to blog.rb (which should be simplified even more, and actually work). The
book could then take it from there and slightly expand into the blog.rb (or
maybe even totally different; we should at least end up with something)

You know, I remember stumbling on Camping after trying out Rails, and it was
a horrible feeling ending up at page 3 of the tutorial (on the old wiki)
where a giant "TODO" screamed at me. I think many newcomers would have a
look at alternatives to Rails, and it would be great if we could guide them
not only through Camping, but also on the way you have to think when you're
developing on the web. Without boring them too much. At the same time, there
will probably be some Rubyists/webdevs who just want to learn about Camping
too.

What if we start easy with lots of code and introduce them to Camping, then
(if we bother to) more in-depth about the web, HTTP, GET/POST/PUT/DELETE,
limitations? You could follow the book right through and will end up with
basic understanding of the web, or just skip after the quickstart (and three
months later, after you've experimented a bit, you take the trouble to
trouble to read the rest).

Maybe "book" is the wrong word for this too. A book is so formal and strict.
This should be light, simple and something you just can dive right into
whenever you want. Let's keep it simple and precise, yet informal!

The API as a cheat is a great idea too, let's not forget that :-)

When it comes to the dependency on Rack, I'm not that worried. You almost
can't do any webdev in Ruby today without meeting on Rack. And you only need
to have the Rack-library somewhere where Camping can find it (just download
and unzip it to vendor/rack for instance), even though using the gem is
preferred.

Anyone else want to chime in? (Yes, you do!)

I currently have some RDoc templates which renders the book/readme/api. It
definitely needs to be cleaned up a lot, but I guess I can push it out at a
branch when I get back to my computer.

//Magnus Holm


On Tue, Jun 9, 2009 at 19:30, Dave Everitt <dever...@innotts.co.uk> wrote:

> I'm quite good at clear an understandable English (and editing the work of
> others) so would be glad to help make the documentation as usable as
> possible.
>
> I reckon we need two starting examples somewhere (a download link in the
> README?):
>
> 1. 'It worked - you are now Camping!' (without a DB);
> 2. a foolproof version of the minimal blog.
>
> I think you're dead right about the two kinds of users and three parts of
> documentation. As for the book (WebDev with Ruby, using Camping as an
> example?), it would be good to follow the spirit of Camping and keep it
> under... well, not 4k, but you get the point. The Camping philosophy needs
> to pervade the docs too - there's cultural capital in it, which could become
> a real attraction.
>
> I also suggest putting up the '1-page API' on 'cheat'.
>
> I have one slight concern for those on shared hosting: that it's 'not
> possible to run Camping without Rack'. It might take some thinking about how
> best to do this without root (or how to ask your provider to add the
> necessary). Many prospective Campers won't change servers just to try
> something out. Not necessarily an obstacle, but it needs some thought (a
> cleaned up pre-rack version? Camping 'classic'?).
>
> DaveE
>
>
>  Oh, yes. Let's (once again) try to clean the documentation up a bit :-)
>>
>> I have no facts behind me, but I assume there would be two kinds of people
>> who would like to browse camping.rubyforge.org:
>>
>> 1. Beginners who want to know what it's all about, how to get started and
>> how to get help.
>> 2. Campers who don't quite remember which method to use, or where the
>> mailing-list was located, or how you did X etc.
>>
>> So here's a little proposal: What if we split the documentation into three
>> parts?
>>
>> - README.txt should be the first you see and should contain basic info and
>> links.
>>
>> - API-reference. A one-page reference to the whole Camping API which gives
>> you short descriptions/explanations and might also give a link to the book
>> (see below) for more detailed thoughts.
>>
>> - A "book" or tutorial which guides the user from A-Z, starting with
>> installation and how to use The Camping Server, through basic MVC and
>> HTTP/REST to how to use service-overrides or middlewares. It would be really
>> nice if this could be a clean, short and concise guide to both Ruby and web
>> development.
>>
>> What'd you think? What do you miss most from the current (almost
>> non-existing) documentation?
>>
>
> _______________________________________________
> Camping-list mailing list
> Camping-list@rubyforge.org
> http://rubyforge.org/mailman/listinfo/camping-list
>
_______________________________________________
Camping-list mailing list
Camping-list@rubyforge.org
http://rubyforge.org/mailman/listinfo/camping-list

Reply via email to