|
A few days ago, Dave Winer pointed to Charles Miller who complained about the documentation problem with Radio 8. That got me thinking, and this post is the result.
Radio has two audiences: writers and developers.
UserLand treats its writer customers very, very well. The application built in to the Radio platform makes writing for the web easy and powerful. Five minutes, and someone who knows very little about technology can be writing to the web. That's incredible power, and UserLand deserves every single accolade its gotten on that, and more.
UserLand treats its developers well too, but only ones that already know what they're doing. Once you've begun developing in Radio the world is your oyster... the question is, how to start? Dave's Going Crazy with Macros tutorials are a good intro, but they don't go very deep. I can sum up the newbie developer's problem in one word: documentation. The lack of easily-found, easily-navigated documentation is a huge barrier to entry. In order to write your first meaningful Radio extension, you have to do a ton of digging. I've been banging my head against this barrier for a while now, and I'm slowly beginning to break through. Here's a list of the most irksome problems I've had, and pointers to docs to help you get going.
- You have to understand the UserTalk syntax (there's a pretty good document on that here)
- The concept of the Object Database (I just found this).
- The verbs available (excellent documentation here, but I don't know if it's complete for Radio)
- The built-in Radio macros (some of which are here, but I have yet to find a comprehensive list)
- The intricacies of the Page Table. This will get you started, but you have to do a prohibitive ammount of trial-and-error for each web form you write. Good luck finding that document on your own; I've read it a number of times, and it took me a while to find it again. I have yet to find a good, definitive document.
- Random built-in functions. The document pointed to in the last item mentions, almost as an afterthought, the edit() function (macro? verb?). I never would have known about it if it wasn't in that document, and it's the only thing that makes coding form handlers possible. There are probably other things like this out there, but I don't know what they are.
- Understanding table values as opposed to addresses can be tricky. You have to understand the @ and ^ operators. For instance, in a tutorial somewhere (I forget where) there's something like the following code: @pta^.foo. This made no sense to me until Garth at Deadly Bloody Serious helped me out. The groupings in that piece of code are non-obvious, but here's how to think of it: @(pta^.foo) (note: that syntax probably doesn't work, but it expresses the concept). If that doesn't make sense to you now, that's okay, but remember it, it'll come in handy.
I'll keep digging, because that's the way I am (to the great chagrin of my fiancee). I'll let you know what I come up with. |
