A few posts ago, I mentioned that I'm working on some end-to-end solutions docs for the next release of Microsoft Speech Server. This will be my big contribution; my innovation. That's a buzzword 'round these parts. Sure, I've got a hundred other things on my plate, some of them interesting, some challenging, some fun (kind of). That's just the way things are in the daily product development grind here in Redmond. You sign on to work for Bill, you get to do lots and lots of work, whether you like it or not. But, for my money, these solutions docs pass the muster on all counts: interesting, challenging, and fun (kind of).

I feel your pain
Most documentation we software tech writers have foisted upon users over the years has been overtly task-based. Got a problem? Look in the Help file. Maybe the answer is there, maybe it isn't. Hey, we wrote these docs before the product even shipped—you can't expect us to anticipate every single corner you're going to back yourself into. If you can't find your answer in the Help file, you can always look in a 3rd party book, search the web, or phone a friend. Could be costly. Good luck.

That didn't work so well. Customers were too often left hanging with no solution to their problem and nowhere to turn. We've come a long way since then. What with online newsgroups, feedback loops, discussion lists, and the like, Microsoft has gotten downright chummy with customers over the past few years. These days, you can get your questions answered 24 hours a day. If your specific problem isn't addressed in the Help doc, it's not such a huge deal anymore. But what about proactive guidance? That's where solutions come in.

Enter: Solutions docs
Now, I'm not saying that these solutions docs are going to be the Alpha and Omega of Help files. They won't be. But they will offer a point of reference for Speech Server customers (new customers in particular), enabling them to identify with a real-world implementation, and maybe, just maybe, hold their hands through the entire "installation-deployment-engineering-tuning" process, ultimately erasing some of the question marks that hover above their heads. Like any good technical docs, the solutions will be replete with diagrams and cross-ref links, and will provide a strong context for customers who want to build their own speech solutions. (Hence, the use of "end-to-end.")

My high-level outline for each solution looks like this, though I’m still tweaking it:

  • Overview (intro, business problem to be solved)
  • Installation & Deployment (architecture, topology)
  • Administration (configuring servers, speech engines)
  • App Development (call flow, how to write apps for debugging/tuning)
  • Tuning (tools)
  • Best Practices (incl. security issues)
  • Upgrade & Migration (retrofitting implementation/apps for v2)

Looks like fun, doesn't it (kind of)? As I said, I've yet to settle on the final outline, so if you have any suggestions for improvements, now's the time to tell me.

Cup o' Joe
With Phil the Coffee Junkie in California all last week, my life was caffeine free, save for the time I helped myself to a cup of Farmer Bros. in the Break Room. Not bad in a pinch, but I'd hate to rely on it for my daily fix. Anyway, Phil is back, and this morning he brewed up a steaming pot of Museum of Delta, which I think is a mixture of a bunch of little Delta (Portuguese) coffee packets — all different flavors, of course.

Result: Full taste with a hint of caramel; slightly bitter, but doesn't dull the senses. Reminiscent of an after dinner libation served in a dimly lit Iberian tasca with small tables and a waitress named Conchita.