De-smalling the Built-in Shoes Manual
Shoes must cease growing to keep claiming its tinyness. Except for the manual. Let the manual bloat. I want a fantastic manual. The manual is pretty much the best Shoes app out there!
This is the built-in manual. It’s not terribly gorgeous yet.
Use: shoes -m. Or Alt-Question-Mark on any Shoes app. And there it is. (In recent builds.)
If you’ve not heard of Shoes, it’s a kit for writing graphical apps in Ruby. I hope that it strikes balance between easiness and usefulness. Some folks write games for Shoes. I’m writing a teaching tool in Shoes. The kit is pretty flexible, but concentrates on doing a very small number of things well.
Like, for instance, there are ten essential commands in Shoes that are used in absolutely everything.
Beyond those ten things, though, are a hundred more things.
Shoes has about a hundred methods total for creating new elements, applying effects, manipulating the app, events, and all of that. Most of these things just give beginners a place to go once they get past the basics.
Add another hundred methods on top of that among all the various objects you can create.
Rather than memorizing those methods, I recommend to beginners that they commit only the ten essentials to memory. And, for everything else, use the manual’s built-in search.
Looking to draw a rectangle? Use the search.
No submit button, it searches as you type.
Search results display as a list of links throughout the manual. Method links take you straight to that method.
I’m only halfway completed with documenting Shoes. But, it will be done for the next release.
For me, having a good manual is more important than even Shoes’ stability, perhaps. As one of the only app kits out there focused on beginners, it’s crucial that Shoes become an example of how to innovate the way people learn. I think having a really capable search in the built-in manual is a huge part of that.
Another part is having a lot of examples that can be executed right there in the manual text (like you see with docs for jQuery or Scriptaculous.) Processing’s docs definitely benefit from having working applets next to their examples.
To have the freedom to alter the code in the docs to get some understanding might really have an impact.
Hackety.org is for artful computer hacking. Hobbyists & amateurs welcome. Business trends and language wars? None for us, thankyou! More.
Elsewhere
- Shoes
the Ruby app toolkit - Hackety Hack
the coder's starter kit - Try Ruby!
a hands-on tutorial
brainopia
Great stuff!
someguy
Thanks, this is really nice. It lowers the overhead for doing truly interesting stuff. I hope good things come your way for all of your hard work.
kamran
Thanks for taking the time, this is just what i was looking for, quick searching NKS doesn’t work so well because much of the reference material isn’t text, but images of text. Keep up the great work!
_why
Much obliged.
There are also new distros out for Windows and Linux today.
OS X has a few critical bugs preventing release, but will be done in a day or so.
kamran
hmmm, when i updated from r605 to r646, the video support quit working. I did ‘make VIDEO =1’, is this out of date now? thanks.
zerohalo
Excellent! I completely agree that a very thorough manual is one of the greatest benefits of a toolkit aimed at beginners and makes Shoes an excellent teaching tool. Thanks again.
Cane
“Shoes must cease growing to keep claiming its tinyness.” Does it mean that you think that Shoes will soon reach the point in which you will use it as a part of Hackety Hack?
Dale
How do I print the built-in manual?
How do I print the built-in manual?
How do I print the built-in manual?
netghost
Could it be possible to get shoes as a gem or a library sometime? I’m not sure what custom shenanigans were required to make the shoes distros.
also netghost
Oh and a resounding sound of one hand clapping in the woods for _why.
brianmuckian
_why…have you lost the link to OLPC ? I’d really love to fit mine with a nice pair of shoes y’know.
someguy
Any word on the OS X update?
Guoliang
Very exciting project!
Are you planning to make shoes a gem very time soon?
I guess if shoes is a gem, then shoes app can be released as gem too.
kamran
Shoes isn’t shipped as a gem cause it’s a ruby distro, it’s got everything you need all packaged up, makes distributing your app easier.
Guoliang
That’s very reasonable. However, before I release my own shoes app, if I want to play with Shoes or poke around other shoes app, downloading as gems is easier for me cuz I already have ruby installed. IMHO , ideally, I should be able to do
gem install shoes
gem install tetris
shoes tetris
I would have to navigate to ruby/lib/../gems/../tetris directory to read tetris’ source code but that’s fine.
Just my 2 cents :-)
kamran
Meh, I think it’s nice how it’s all sandboxed, right now it’s basically as simple as: extract, make VIDEO =1, make install, shoes tetris.shy
It seems like less work to me than having to dive way down into the ruby directories to add libs or run samples. Plus, you can throw it on a thumb drive, and have a little portable shoe factory. I think the benefits outweigh the easyness of a gem, though the project is really in its infancy right now, so who knows, maybe once things are a little further along we will see a gem version. :)
_why
And better than a gem version will be stable debs, rpms, ebuilds and so on.
So, could be:
Comments are closed for this entry.