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? //Magnus Holm -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://rubyforge.org/pipermail/camping-list/attachments/20090609/4c7e6c09/attachment.html>
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?
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 <deveritt at 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 at rubyforge.org > http://rubyforge.org/mailman/listinfo/camping-list >-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://rubyforge.org/pipermail/camping-list/attachments/20090609/926e3541/attachment.html>
Hello Campers...
I''ve just finished a (hopefully) nicer-looking Camping 1.5 blog
example, adapted from one of the originals:
http://pastie.org/560295
Things I''ve done:
added a delete class,
combined the add/edit/delete method into one,
made a little ''cooked up while camping'' logo,
tweaked the CSS so it looks kind-of-ready for deployment,
called it ''tentpole'' because it''s so simple
(that''s a joke).
I know there''s the clean, new example for v2 on Github, but I
don''t
have Camping v2 up and running yet (I will, soon), so this is for
anyone who needs to point to a simple, working a 1.5-ready example
with minimal setup requirements.
Still keen on Magnus'' documentation ideas (below) and happy to
start... I think the book should be a Camping app :-)
Dave Everitt
> 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)
Magnus'' documentation 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.
While I can''t have a look at it at the moment (no Internet access), it''s very nice of you! Maybe we can merge them and get an even better blog.rb in v2. As for the documentation ideas, I''ve already implemented the templates in RDoc, so "rake docs" builds all the three parts (the book is simply files in the book directory). I still need to make a way to link book chapters from the reference, but at least it''s working. A Camping app can be useful when you want to edit it, so you don''t need to run the rake task all the time. I guess we could also implement it as a wiki, which might be better. Then we can''t have it on camping.rubyforge.org (unless we can change the DNS-settings) though since it only allows static files. What do you think? I prefer having everything in files, and I think those who really want to contribute to the book wouldn''t mind a "git clone"... Right now I''m on vacation, but I''ll try to push it out when I return. Feel free to write some paragraphs if you''re really keen, I only have a bare skeleton. //Magnus (written 28th July in offline mode) On 27. juli 2009, at 16.57, Dave Everitt <deveritt at innotts.co.uk> wrote:> Hello Campers... > > I''ve just finished a (hopefully) nicer-looking Camping 1.5 blog > example, adapted from one of the originals: > http://pastie.org/560295 > > Things I''ve done: > added a delete class, > combined the add/edit/delete method into one, > made a little ''cooked up while camping'' logo, > tweaked the CSS so it looks kind-of-ready for deployment, > called it ''tentpole'' because it''s so simple (that''s a joke). > > I know there''s the clean, new example for v2 on Github, but I don''t > have Camping v2 up and running yet (I will, soon), so this is for > anyone who needs to point to a simple, working a 1.5-ready example > with minimal setup requirements. > > Still keen on Magnus'' documentation ideas (below) and happy to > start... I think the book should be a Camping app :-) > > Dave Everitt > >> 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) > > > Magnus'' documentation 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. > > > _______________________________________________ > Camping-list mailing list > Camping-list at rubyforge.org > http://rubyforge.org/mailman/listinfo/camping-list
Hi Magnus> While I can''t have a look at it at the moment (no Internet access), > it''s very nice of you! Maybe we can merge them and get an even > better blog.rb in v2.very happy to do that, but you''d better take a look first - I''m still in both the Ruby/Camping shallows here, and also new to github...> As for the documentation ideas, I''ve already implemented the > templates in RDoc, so "rake docs" builds all the three parts (the > book is simply files in the book directory). I still need to make a > way to link book chapters from the reference, but at least it''s > working. A Camping app can be useful when you want to edit it, so > you don''t need to run the rake task all the time.I''ve generated an entry on rdoc.info (BTW it uses Sinatra!) and it''s done a very nice job of presenting the documentation, which can now be updated anytime: http://rdoc.info/projects/judofyr/camping> I guess we could also implement it as a wiki, which might be > better. Then we can''t have it on camping.rubyforge.org (unless we > can change the DNS-settings) though since it only allows static > files. What do you think? I prefer having everything in files, and > I think those who really want to contribute to the book wouldn''t > mind a "git clone"...since rdoc.info above now does the job, I guess the Github wiki can serve to capture and edit user community knowledge. That''s everything covered? Apart from a dedicated website, of course :-)> Right now I''m on vacation, but I''ll try to push it out when I > return. Feel free to write some paragraphs if you''re really keen, I > only have a bare skeleton.if I find anything missing, or I can''t understand it, I''ll make suggestions about small edits for clarity. Dave>> On 27. juli 2009, at 16.57, Dave Everitt <deveritt at innotts.co.uk> >> wrote: >> >>> >> Hello Campers... >> >> I''ve just finished a (hopefully) nicer-looking Camping 1.5 blog >> example, adapted from one of the originals: >> http://pastie.org/560295 >> >> Things I''ve done: >> added a delete class, >> combined the add/edit/delete method into one, >> made a little ''cooked up while camping'' logo, >> tweaked the CSS so it looks kind-of-ready for deployment, >> called it ''tentpole'' because it''s so simple (that''s a joke). >> >> I know there''s the clean, new example for v2 on Github, but I >> don''t have Camping v2 up and running yet (I will, soon), so this >> is for anyone who needs to point to a simple, working a 1.5-ready >> example with minimal setup requirements. >> >> Still keen on Magnus'' documentation ideas (below) and happy to >> start... I think the book should be a Camping app :-) >> >> Dave Everitt