« Body Modification | Main | Tracking Construction Progress by Satellite »

February 26, 2008

The Wiki and the Handbook

There are two internal sites at Microsoft which have similar goals, both under the aegis of Engineering Excellence: the EE wiki, and the EE Handbook (the internal URLS are http://eewiki and http://eeh, respectively).

The wiki is a wiki, whch means that anybody can modify anything at any time. It does track the corporate network login of the person making each edit, so outright defacement is unlikely, but other than that it's fair game, and if you make an edit it is immediately available for everybody to see (right now, most of the edits are done by people in Engineering Excellence; one of the things I've been doing to try to change that is have every class I teach make at least one edit to the eewiki, however trivial, so they get a feel for how easy it is). The wiki is very convenient place to put information, for example for any topic that we teach such as formal inspections, the eewiki page will have a section "teams at Microsoft using formal inspections" and we ask people to add themselves to the list if they are using them.

There is also the Handbook. This is a website running on technology developed within EE for the specific purpose of hosting the Handbook (the eewiki currently runs on FlexWiki). It has a sophisticated layering model where there is a base handbook, then teams can replace specific pages, or let them flow down from the base page, and so on down the hierarchy. Also, there is a workflow involved in making changes, in which they are shepherded through by people in EE (such as myself), submitted to a team of editors and content architects, and then updates are queued up and published on a regular basis.

It's the standard short head vs. long tail situation, and you may not be surprised to hear that on the dev excellence team, anyway, the eewiki is winning out. We do occasionally drive Handbook changes, and there are useful pages in the Handbook that I show off in class, but our go-to place for storing information is the eewiki. This includes both stuff that is internal to our team (such as outlines of courses under development) and material intended for the broader Microsoft audience. So the experience for somebody outside our team (but inside Microsoft, of course, since the eewiki is only available on the corporate network) is a mish-mosh.

I think a bit of it is that we're being lazy and don't want to deal with the Handbook workflow, so we make the quick eewiki edit without worrying whether it is the best experience for our customers. But I also think that there is something "developer-y" about favoring a wiki over something more formal (other teams in EE have different balances of wiki vs. handbook; I'm pretty sure the dev team is the most wiki-centric). The fact is that the wiki is a much closer approximation to how we write code. The trend in software development these days is to be more "agile" and empower people to complete things on their own, and the wiki definitely fits in that model better than the handbook. So for better or for worse, it's no surprise that we devs feel more comfortable there.

Posted by AdamBa at February 26, 2008 09:31 PM

Trackback Pings

TrackBack URL for this entry: