Wednesday, 24 January 2007
12:13 AM
Anyone with an interest in ASP.NET AJAX -- aka "Atlas" -- will know that we released the official 1.0 version this morning (Tues). I don't have anything to add to the technical discussions that have been going on all day. But I will repeat something that I think has been noted several times, which is that this is one of the first, if not the first, fully supported Web-based release of a Developer Division product. (Lots of tools have gone out on the Web, of course, but this is a full-on 1.0 release of a product.) The standard way in DevDiv to release products is in, effectively, a shrink-wrapped box, virtual or otherwise. Updates generally require an SP release or might be bundled into a Windows Update installation. In contrast, ASP.NET AJAX has followed a much more agile model (in both the generic and technical sense); the development process was in a tight development cycle and new preview releases were posted roughly every other month. As you know.
This has been a new approach for us in documentation as well. For starters, the documentation has been released on the http://ajax.asp.net/docs Web site right alongside the bits. If you ponder for a moment, you'll realize that normally all DevDiv documentation is released via two channels, and they're both spelled MSDN. When you install a product, there's an option to install the docs locally, which downloads .hxs files and the viewer. Or of course you can go to MSDN online (http://msdn2.microsoft.com). For ASP.NET AJAX, though, this wasn't going to work for us. The publishing process for MSDN just isn't set up for the kind of doc release we needed; we needed to be able to push docs out on a very tight schedule, plus there were a couple of other things that made the big ol' MSDN machine not so suitable for our agile little doc set.
So some extremely hard-working guys on the doc team essentially invented a way to publish to the ASP.NET site. We're able to use the same authoring tools (Word, of course) and our content-management system and so on. The new publishing process takes the same output that we produce (XML, basically) and runs it through some custom transformations, sprinkles some CSS in, and produces a doc set published as .aspx files and suitable for FTP-ing to the server. Presto. If we want, we can put a new doc release out any old time we want with just a couple of hours' notice.
This is all behind-the-scenes stuff that you don't really care about, other than the results. One of those results is that we'll be able to push out a doc refresh quickly, which we're hoping to do (fingers crossed) in a comparatively short while. At least, it won't require a quarterly release from our normal publisher. :-)
Update 24 Jan 07 Gee, I forgot to note one feature we were able to implement by using this new system -- the Run It and View Source buttons for sample code. Just like the QuickStarts!
Just like the Dev team, the doc team was able to be more responsive -- to bugs, to changes in the software, and to feedback. After the Beta release, we got feedback that we should do more tutorial-style docs. So we concentrated on that and by the RC release, we were able to post a nice selection of walkthroughs.
There were some other challenges. For API reference, our publishing tools use .NET reflection to discover types and members, which is darn handy. That worked great for the server classes like UpdatePanel. But a big hunk of the docs (435 topics, if I remember right) were JavaScript API topics, and we couldn't use regular reflection for those. Those the writers had to stub out manually, combing through specs and (ultimately) through the source code. Not only was this inherently a manual process, but staying on top of the quickly changing APIs was that much harder. Our publishing tool also tests code snippets by at least compiling them; we just didn't have the same level of tool support for JavaScript examples.
To some extent we were developing new ways to work as we were actually doing the work. It has made us investigate what people know about "agile documentation." There's tons of information (and opinions) about agile development, but not very much about documentation in the context of agile. (And most of that tends to be about developer-created API docs that are generated from comments.) Documentation is almost by definition a little more reactive than dev work. (Not as much as editing, ha!) You can write some documentation from spec, but you do really have to be able to touch the product to write, say, tutorials. Moreover, when developers are agilely developing on short cycles, there simply isn't as much time for technical review and other tasks that we need to do.
We've talked to people who've got some experience with the agile model. Some teams simply plan on being one cycle behind the dev team with each release. We also heard about teams that focus their efforts on a particular area for each cycle; each doc release accumulates more docs, one area at a time. In our traditional model of releasing docs only in conjunction with a major product release, these would not be acceptable strategies. But the process we developed (and continue to develop) for the ASP.NET AJAX documentation gives us much better flexibility in planning and releasing new docs and updates.
The whole ASP.NET AJAX development sure has been interesting in many ways, and this is (to us) another. The success of the whole project -- both how it was developed and how well it's been received -- have made it clear that we'll be seeing more such development projects. Although it hasn't always been fun to figure out how to do the docs within this process, we made some major leaps forward with this 1.0 release, and we can only get better at it. :-)
[categories]
aspnet, writing
|
link
|