De-smalling the Built-in Shoes Manual

May 31st 21:09
by why

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.



said on May 31st 17:14

Great stuff!


said on May 31st 20:38

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.


said on May 31st 21:01

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!


said on May 31st 21:10

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.


said on May 31st 21:33

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.


said on June 1st 11:18

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.


said on June 1st 19:17

“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?


said on June 1st 23:37

How do I print the built-in manual?

How do I print the built-in manual?

said on June 1st 23:38

How do I print the built-in manual?


said on June 2nd 11:34

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

said on June 2nd 11:35

Oh and a resounding sound of one hand clapping in the woods for _why.


said on June 3rd 01:51

_why…have you lost the link to OLPC ? I’d really love to fit mine with a nice pair of shoes y’know.


said on June 6th 07:45

Any word on the OS X update?


said on June 12nd 09:48

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.


said on June 12nd 23:55

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.


said on June 13rd 08:53

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 :-)


said on June 13rd 13:41

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. :)


said on June 13rd 15:24

And better than a gem version will be stable debs, rpms, ebuilds and so on.

So, could be:

 apt-get install shoes

Comments are closed for this entry.