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
[email protected]
http://rubyforge.org/mailman/listinfo/camping-list
