<D <M <Y
Y> M> D>

wadl.rb: If you like REST web services I have something for you. A while ago Marc Hadley came up with a service description language called WADL. I now have a primitive proof-of-concept Ruby WADL parser/client that can read a WADL file and call simple web services like the Yahoo News search. (I emboldened that link because there are so many other links in this entry, and that's the one this entry is about.)

Right now every REST web service is slightly different. You access them all with simple tools: your language's HTTP library, and probably its XML parser. Which is great because it keeps the services simple. What's not so great is that you have to learn each REST service separately.

What's more, it's useful to package and distribute your implementation of a particular service in a particular language. There's PyAmazon and Ruby/Amazon and a4j, PySearch and Yahoo-Ruby. That's always seemed wrong to me.

With a SOAP/WSDL service you just load up the WSDL file and call or generate the native language methods. Even though the underlying technology has more layers and is much more complex, when WSDL is one of those layers (and nothing goes wrong), everything just works. Sometimes there are language-specific wrappers on top of a SOAP/WSDL service (PyGoogle and Ruby/Google), but they don't do much: they make your code look nicer, or compensate for the shortcomings of the underlying API.

WADL is the best way I've found to get that ease of use for REST services, without creating documents that don't make sense to humans, or selling out the resource-oriented architecture of the web. WADL is very human-readable and it describes resources, dammit. I like it a lot and I think it'll make things easier for programmers if it gets widely adopted.

[Comments] (3) IF Score System Design, Plus, a Writer's Plea: The above-any-adequate-alliteration-allowance 'First-Timer Foibles' guide to writing IF got passed around a lot among my friends, so I want to talk about that a little bit. This is mostly based on email conversation with Adam Parrish, who I just realized has the awesome job of studying interesting things like IF. I knew about his job, but not that when we talk about this over email I'm slacking off and he's working. Actually now I might be just making stuff up.

First a note about pages like that, which as a good IF writer but a middling static fiction writer, I find kind of frustrating. The page is oriented towards beginning writers. Like most web pages that allege to help you be a writer, it's heavy on "don't misspell words" and less heavy on "don't have a hackneyed plot" and "don't create puzzles that make no freaking sense" and things I don't know or can't articulate. Such pages turn bad writers into readable bad writers, but won't get anyone's work up to really good quality. As I've found out the hard way, good ideas and a good grasp of English don't automatically translate into readable stories. There are additional skills.

These pages chop the head off of a Sturgeon's Power Law that says the vast majority of bad writing is bad for obvious reasons (scroll down to the handy "context of rejection"). With static fiction I can routinely hit the midway point on this particular ring-the-bell carnival game, but I haven't found many good resources for getting higher. I have found one extremely useful page, but the higher-level craft seems to be something you have to learn one-on-one with someone who already knows, or something subjective you learn with practice. Or something that no one has written about because existing documents are enough to get the unintersting people out of your hair.

The problems in the first-timer list are divided into problems of fiction and problems of game design. I'm not going to discuss the problems of fiction because I don't find them very interesting. I can, however, tackle the problems of game design because much less work has been done exploring elementary problems in game design. Because this entry is already huge I'm going to cover one item at a time, over a period of several centuries.

Item 1: bad point systems. There are actually two possible problems here. The first is a poorly-scaled point system where you get 100 points for finding a key. The second is an overgenerous point system where you get 5 points for getting out of bed.

If a piece of IF has a scoring system, it imposes a limit on the score. I don't know of any counterexamples. In general, your score goes up when you do a one-time action that progresses you toward the conclusion of the plot. Your score at any given time is a measure of your progress (Zork III is a notable, and obnoxious, exception).

But if a video game has a scoring system, it imposes no limit on the score (except any imposed by the hardware). Again, I don't know of any counterexamples, though I can conceive of games where your score is represented as a percentage. The score of a video game has nothing to do with the game per se: your advancement towards the end of the game is measured by things like stage numbers. It's just a way of keeping... score. I think this problem is caused by treating a piece of IF like a video game.

It's fine to give the player 100 points for finding a key in a video game, but ridiculous to do the same thing in a piece of IF. This is because people don't handle big numbers well. If your maximum score in an IF game is a big number, it's difficult to tell how close you are to the maximum, and how much 100 points really contributes towards the maximum. A big inscrutable number is cool when you're claiming to be an awesome dude, but it's not as cool when everyone who completes the game gets approximately that same score.

By the same token, you shouldn't give out points for actions that don't advance the plot or don't involve any cleverness. If you do, the score will cease to have meaning as a way of measuring the state of the plot and your cleverness so far.


Unless otherwise noted, all content licensed by Leonard Richardson
under a Creative Commons License.