I love demo apps. When coutenay came out with his rails demo app I learned a lot. I’ve since created a few feature-specific demo apps and I hope that others can learn something from them:
As I’ve built these, I’ve realized that it would be helpful if all of these demo apps had a similar structure, so I’m going to propose one here. If you have any thoughts, either fork one of those apps at the top and add them to your fork, or add comments here below. Here’s my first round of thoughts:
There should be a demo app start kit
This starter kit would have a readme with a README.rdoc page with a few sections outlined already, like “Installation”, “What this demonstrates” etc…
Another great feature for a starter kit would be a helper that reads source files and displays them, syntax highlighted, to the users so that while you are looking at a page in the app and you say “what does the controller look like for this page” you could just click “view the controller code” and have it appear.
Yet another feature that would be slick in a demo app would be a page that detects whether or not the database is installed, and if not, provides you with a simple database configuration form that allows you to specify the provider, username/password and optionally the timeout or the socket.
The idea for the starter kit would be to make it easy for developers to create a starter kit that “just works” by installing the app and running script/server.
Vendor everything
Rails makes this easy with the new gem dependencies, but I think all rails apps should have vendor/rails and all of the related gems vendored. I haven’t been consistent about this with my demo apps, but I realize how this would be important.
Pre-populate the database
Whether you use the dataset plugin, custom rake tasks or sqlite3 databases prepopulated, every demo app should have an initial dataset so people can test the full range of the app without having to first add data – especially important for things like the complex forms demo, where the app shows how multiple models relate to each other.
Demos should ideally have specs
I haven’t put meaninful specs into any of my demos, but as people download them and point out bugs I realize how helpful they would have been. I hope to add specs to these apps as time goes on and fix whatever bugs I find. If you do this, be sure to vendor your rspec/rspec-rails along with your vendor/rails.
Documentation should be redundant
Things that are in the README should also appear on the actual rendered pages, as well as in the source code. When developers first load up the app it should be obvious what’s happening.
Again – I haven’t done most of these in my demo apps, but I realize how important they would be, especially if more than 1 or 2 people are downloading the app. If someone is checking out your demo app, it probably means that don’t know how to do whatever you are demonstrating, and a long or frustrating demo (or a buggy one) can be worse than none at all.
Have you built a demo app? Any other suggestions or anything I’ve missed?
