documentation toolkit

Ok, I'm a geek. But it'll be good for the project, once they get used to it. :-)

Our company makes an SDK (software development kit). That means that we sell our product to people who then use it to make their own products. We provide documentation for those programmers. We also provide the building blocks of a user interface, which they can use or not.

It was only a matter of time before we had to start worrying about user documentation for that interface. Now, we can't just do up a user guide for the interface, because our customers can modify it and need to be able to produce their own customized user guides to go with. And we can't, it turns out, just make them do all their own user documentation. (We currently provide a quick-start guide, a UI cheat sheet of sorts.)

So I'm now thinking in terms of a "UDK", a "user doc kit". Like the SDK, we would supply building blocks and they would put them together as best suits their needs. As with the SDK, we would provide a basic implementation that makes sense and that they can use if they like.

I know I'm not breaking new ground here, but I'm enjoying thinking about the parameters of the problem so I can structure it appropriately. (It even makes up for the prospect of having to write some of that user doc...) We need to support people using everything from HTML to Word to Frame to some Mac-specific PageMaker-like tool (I don't know its name), so it looks like I'm going to settle on unformatted text files and standard graphics formats (JPG, PNG, etc) as the portable common format. I'd like to do something a little richer than that; we'll see. (I proposed XML or HTML but they didn't like that.)

We have a project in-house that needs user documentation, so I'll have a handy guinea pig. They asked me for help with user docs; I sold them this approach instead, which is generalizable. It would be stupid to just do a project-specific user guide and later raid it, cut-and-paste style, for the next project that needs this. Besides, this way we can package the bits for customers, too.

last few days

Tonight for the first time the choir sang "Hashkiveinu" all the way through and approximately correctly. Yay! I really like the sound of this piece; the chain of suspensions at the end is especially cool. Rossi had some odd ideas about harmony in places, but this one works.

Sunday dinner featured a small grilled turkey with rosemary and apricot coating. (Ralph says there was also garlic, though I didn't detect it.) This worked really well! I wonder if I can simulate this in an oven, perhaps with chicken. (Though this turkey was small enough that it wouldn't produce ridiculous amounts of leftovers.)

After dinner we played a variant of Carcessan (which I've probably misspelled) called, I think, Hunters and Gatherers. I've only played the original game once, so while I recognized the game system, I didn't really know how to play. I wasn't doing a very good job with long-term strategy, though I was doing ok with short-term tactics.

Sunday afternoon we went shopping to replace the wall-to-wall carpet in the basement guest room that destroyed by the rain invasion a couple weeks ago. First we went to Home Depot, who advertised installation services, but it turns out they don't install indoor-outdoor carpet, only the regular kind. So we ended up at a carpet place, where we ordered the carpet and someone to make it all fit, which is supposed to happen sometime next week. It's an L-shaped room with some cabinets and stuff to work around, so there was no way we were going to do this ourselves. They have a fixed price for carpet plus installation, based on square footage of the piece of carpet you have to buy (which is larger than the space it goes into, especially in this case). Charging for installation for the part of the space they don't install into seems wrong, but they didn't ask about complications like cabinets so it probably works out in the end.

Saturday night we went to a party hosted by friends who had recently returned from a trip through wine country with, shall we say, excess potables. I had a red that I actually liked and that wasn't ridiculously sweet, though I failed to record what it was. (I can find out, though.) There was much good food, including several very nice cheeses. I'm going to have to go in search of good cheese locally. And, of course, much good conversation as well.

I spent some of Saturday afternoon continuing to work through the Torah portion. I'm pretty comfortable with about two thirds of it. I hope to get the rest soon. The rabbi wants to hear me chant it before he leaves for camp and I have an appointment with him next week for study anyway, so that would be an obvious time.

I'm not fluent in Hebrew, but I know some words and of course I read through the portion in English. As it turns out, the trope often provides additional clues for emphasis, significant words, and so on. It's pretty nifty. Not surprising, of course, but this is the clearest example I've seen so far. This is an action sequence, which works better for that sort of thing than the laws of the sabbatical year. :-)

Friday night was the first service with our new cantorial intern. She's good, and very friendly. It sounded like she was a little nervous; I assume that will pass. At the oneg Phyllis (the administrator) introduced us and she recognized my name; fortunately, that was only because she'd been told I was the chair of the worship committee, and not because of some nefarious reason. :-) (We'll be working together on two upcoming services.)

The fireworks were on Friday, but on Shabbat I have other places to be. I would have liked to go to Ray and Jenn's party, but the logistics just didn't work out. Some other time.