mike's web log

Office space

Sat, 05 Jan 2013 12:34:30 GMT

I spent over 17 years at Microsoft, and for most of that time, the company went to extraordinary and expensive lengths to try to give every full-time employee his or her own private office space.[1] The company kept building new buildings, and every office move — and there were many — involved a substantial effort to sort out seating arrangements so that people could both have their own offices and had some reasonable proximity to their colleagues.

The company's focus on office space presumably was based on an implicit acceptance of the idea that people engaged in concerted intellectual work need to be able to work in peace. In the widely read Peopleware, a book from the mid-1980s about managing software projects, authors Tom DeMarco and Timothy Lister addressed the need for this type of space:

Before drawing the plans for its new Santa Teresa facility, IBM violated all industry standards by carefully studying the work habits of those who would occupy the space. [...] Researchers observed the work processes in action in current workspaces and in mock-ups of proposed workspaces. They watched programmers, engineers, quality control workers, and managers go about their normal activities. From their studies, they concluded that a minimum accommodation for the mix of people slated to occupy the new space would be the following:
100 square feet of dedicated space per worker
30 square feet of work surface per person
Noise protection in the form of enclosed offices or six-foot high partitions (they ended up with about half of all professional personnel in enclosed one- and two-person offices)

[more]

Guard cat on duty

Wed, 03 Oct 2012 06:39:27 GMT

I'm working in a new job, and I was surprised not long ago to get an email from one of our senior developers that read something like this:[1]

To: [whole group]
From: [senior developer]
Subject: I love kittens because they're fluffy

This would be one of yer more wtf new-job moments. A few minutes later we got this:

To: [whole group]
From: [senior developer]
Subject: re: I love kittens because they're fluffy

I stepped out of my office for 30 seconds and I was in the office next door!

There was a reasonable explanation for all this, as it turned out, which involved security. Every company has security policies for computer use, of course, and larger companies might have dedicated IT folks who enforce such policies. One way they might enforce policies is to perform security audits of people's workspaces. For example, has someone written their password on a yellow note and stuck it on their monitor? Fail.

Another policy that the security folks might audit is the practice of locking your workstation when you step away from your desk. Obviously, if you walk away from an unlocked machine, anyone can jump on your computer and start hunting around for sensitive information.

Even a vigilant security audit team, however, can't watch everyone every minute. But I happen to work with a bunch of security-minded developers, so a protocol emerged that if they could catch you with your workstation unlocked, you were fair game to have a fluffy-kitten email sent from your computer. Our senior developer guy, in spite of his protestations, had been caught sneakily when he stepped out for the quickest of conversations.

[more]

Crediting documentation

Thu, 08 Dec 2011 18:19:15 GMT

The standard model for creating large documentation sets pretends, in essence, that the content springs from a single faceless source, namely <Your Company>. This is one of the concerns (not the only one) of a style guide, namely to define an overall tone for a content set that originates with different authors. And of course corporate-created documentation is generally not credited, and certainly not at the article level.

We're starting an experiment with changing this for our own docs. For our last couple of big tutorial sets, we're attaching author names and bios to the bottom. Here are a couple of examples:

In both cases, the author info is at the bottom.

We're also going to be experimenting with adding this info to MSDN topics. Here's an example (actually still a prototype) of what that might look like:

We reckon that adding author attribution has these benefits, in no particular order:

Authors help develop their "brand".
Readers can learn to associate an author's name with a specific level, quality, and focus of work.
Content will get a personality and human face.
Readers get the (correct) impression that documentation is created by actual people.
[more]

Pressure vs stress in motivating employees

Wed, 09 Mar 2011 23:59:09 GMT

Over the years, when I told people I worked at Microsoft, a common reaction[1] was "I hear they make you work long hours!" Depending on how useful it seemed to engage the conversation, one of the answers I had was "No one makes you work any number of hours." This was a slightly disingenuous response, but it is in essence true: most jobs at Microsoft, and in tech generally, are not punch-clock jobs, and I literally cannot recall a boss asking me whether I'd put in my 40 (or 50 or 60, haha) hours.

Long before my Microsoft gig, I wiled away my 20s working lots of 60-hour weeks, happily writing and coding late into the night. Even these days I still like the adrenaline and focus of crunch mode, although as I become, er, more mature, my recovery time from extended days of long hours has become longer.

I was thinking about this because of a piece in Forbes titled Job One for Leaders, in which the author, August Turak, discusses how to motivate employees. "As CEO I always told job applicants that my primary job was increasing pressure while decreasing stress." He goes on to explain the difference:

As leaders, it is our job to increase pressure by giving people reasons to care. We decrease stress by empowering people with all the tools necessary to successfully influence the outcome. [...] Maximum pressure combined with minimum stress produces passion, and passionate organizations full of passionate people will accomplish well-nigh anything. The most important leadership task is providing the ‘whys’ so that others can provide the ‘hows’. Managers get things done, but leaders must decide what is worth doing in the first place and get everyone else to buy in.

[more]

Some love for the Word spelling checker

Fri, 14 Jan 2011 08:55:05 GMT

As I’ve noted before, when spelling-checker software gets attention, it’s because something went wrong. And I’ve also noted before that lots of people think that spelling checkers, and the spelling checker in Word in particular, are not very good.

That isn’t me. I use the spelling checker[1] in Word all the time. In fact, even if I’m writing something in some other editing tool, and even if that tool has a spelling checker, I will often copy the content to a Word document and run the spelling checker there. (This is especially true when I work with HTML documents.) When I found myself doing that again recently, I thought I should sort out why exactly I find it so useful. So here are some thoughts on why the spellchecker in Word works so well for me personally. (As they say, YMMV.)

It’s overwhelmingly right. I am in fact a wretched typist. One of the reasons that this isn’t quite as obvious as it might be is that Word finds the two or three words per sentence that I’ve mistyped and scolds me. People like to harp on cases where Word misses a misspelling (10 Common Errors “Spell Check” Won’t Catch [2]) or suggests some absurd replacement for a misspelled word ("Cupertinos"). But realistically, the percentage of times that Word is right versus these oddball cases has got to be in the high 90th percentile.[3]

It works both in real time and in batch mode [more]

Technical writer interviews: Part 2

Thu, 01 Jul 2010 17:52:34 GMT

Last time I talked a little about the interviewing process and investigating the technical side of technical writing in our group. If you don't pass a technical screen, we're unlikely to pursue the interview. But assuming you do get over whatever bar is set, comes now the writing side.

A diversion. As I will touch on later, there's a difference between a person who can write and a person whose job is writing. A programmer who writes the occasional blog entry is not (yet) a technical writer, who in contrast spends week after week documenting not just the interesting and cool things that are fun to write about, but also the seemingly endless APIs, the unsexy readme files, the installation instructions, and all the other stuff that users need, and who do this on relentless schedules. (As people sometimes say, "that's why they call it work").

Ok, writing. How do you assess writing skills, and specifically technical writing? If anyone's developed a foolproof way, I haven't heard of it.

[more]

Paradox and degrees of separation

Tue, 15 Jan 2008 08:22:41 GMT

My friend P called me up the other day and asked whether I knew of anyone who could program Paradox, which is a database program for personal computers that was released in the 1980s. If this doesn't mean anything to you, you can think of it as perhaps the PC software equivalent to asking your friends if they just happen to have a repair manual for an AMC Hornet, or an LP of the Cowsills.

Friend P doesn't know Paradox, so he called me. I don't know the product either, but I did offer to help find someone. I forwarded Friend P's inquiry to about a dozen people who I thought might either have PC history that goes that far back or who know databases. About two hours later someone replied who had indeed worked with Paradox long ago, and I hooked him up with Friend P.

Frankly, I was not entirely surprised. Naturally, I was not surprised when most of the people I contacted responded with "Nope, not me!" (altho people did remember the software, so I knew my selection of recipients was not too far off). But I was also not that surprised that someone I kind of know proved to be the right contact.

The famous "six degrees of separation" comes from an experiment that was done in the late 1960s in which the experimenter asked people to get a packet to a person in a distant city. The idea was that you could hand the letter to someone who might know someone who ... and so on. There were some surprises that came out of the experiment; the most well-known was how short [more]

Roundup

Wed, 12 Sep 2007 09:05:06 GMT

It's crunch mode again. OTOH, Hawaii in 19 days.

The Tech Battle in Seattle. On the O'Reilly blog, Brady Forrest shows a map of Seattle that indicates where various tech companies -- Microsoft, Google, Yahoo, and Amazon among them -- are expanding their Seattle-area operations. This is good for jobs. Probably bad for traffic.[1] Bad (or good, depending on your POV) for real estate prices.

How to optimize your power strip. I've done some of this (esp w/r/t the UPS) and can recommend it.

Lawyers are always bad PR. Charles Miller has a cautionary tale: "What started as the opinion of a small number of commenters on a medium-traffic Australian forum site is now a portrait of a corporate bully trying to silence critics, splashed over the entire Internet."

The 7 Top employee bungles using Office. Philip Su recounts some of the ways in which Microsoft people have screwed up when using Office. As for #6, a guy I used to work with acquired the nickname "Hotstuff" after he received a, um, personal IM from his wife ... while presenting to the entire product unit.

[1] In case you haven't heard, Microsoft is starting a private shuttle service for employees who commute from selected areas. The company already subsizes bus passes at 100%.

Meeting in Building 7

Thu, 05 Apr 2007 16:41:09 GMT

On the main campus at Microsoft, buildings are numbered. Building 1 was the first one built; Building 2 the second one, etc. (I'm in Building 42.) Much company lore surrounded the fact that there was no Building 7, and a "meeting in Building 7" has been the campus equivalent of going on a snipe hunt.[1]

But the construction boom at MS has by no means ended, and among the plans for new construction was a building that tentatively named Building 7. Ah, the end of the era.

But! Today in the corporate newsletter they had an interview with the chief of facilities. They asked him about the decision to build Building 7. He said that they'd gotten "a lot of feedback saying 'please don't use Building 7,' so we aren't going to use Building 7 as the official name. [...] Interns need not worry; they will still have their missions to go on."

Who says corporations don't have a sense of humor?

[1] One possible explanation here about why there was no Building 7. ScottGu explains further, and also explains why buildings across the street from one another are of such different heights.

Windstorm

Sat, 16 Dec 2006 23:53:37 GMT

Impressive windstorm. Estimated one million people without power in the Puget Sound area at the peak. Power is still not back for tens of thousands of people. By a stroke of luck, I got my power back today, which is a good thing, coz it's 36 degrees outside right now.

Here's a picture I took in my neighborhood.

Update 17 Dec 06 3:30p AFAIK, power is still out to a significant part of the MS campus, including the building that houses the servers that are of interest to my group. I couldn't be working even if I wanted to be. Which is just as well, because my main machine at home turned up dead -- at the moment, I'm guessing a bad power supply, but we'll see. Sheesh, what a mess.

Roundup

Wed, 13 Dec 2006 11:09:40 GMT

An ... eclectic mixture today.

GPS dog collar. Where the heck did that dog go? Here, let me check my mobile phone.

Programmer's Heaven C# School Book. Another free eBook that's an intro to C#. I think that this one contains a particularly clear description of delegates, fwiw. [via The Daily Grind]

Smashing the Clock. "No schedules. No mandatory meetings. Inside Best Buy's radical reshaping of the workplace." Meet ROWE: Results-Oriented Work Environment.

U. scientist makes computing breakthrough. "The technicalities are complex, but the outcome is that if the 'spin' of atoms in a quantum computer could be read, a computer using 64 quantum bits in its calculations would be '2 to the 64th power faster, or about 18 billion billion times faster' than a 64-bit computer of today, the U. noted in a press release. 'Note: billion billion is correct,' the release adds in parentheses."

Holiday Party Excuse Generator. "Answer a few simple questions, and in the time it takes to warble 'Fa la la la la', you'll have an excuse that will either endear or enrage a prospective host." Nice Flash-y stuff. [via Away with Words]

Solio [more]

On the naming of products, part II

Tue, 12 Sep 2006 10:20:13 GMT

A little while ago, I made a few notes about code names for products.

Yesterday Scott Guthrie posted an entry on his blog making an announcement that the product code-named "Atlas" has now got an official name. Actually, three names, because the product is in three pieces: Microsoft AJAX Library, ASP.NET 2.0 AJAX Extensions, and the ASP.NET AJAX Control Toolkit.

Turns out that people can have very strong opinions about names and code names. Here are comments from the blog that opine on this name change:

I'm going to keep calling it Atlas (for a while anyway), it's much cooler ;-)

[...]

I really like the name Microsoft AJAX Library. However, I think “ASP.NET 2.0 AJAX Extensions” is a mouth full to say. Any recommendation for a short name? Also, will the official site still be http://atlas.asp.net/?

Scott: ASP.NET 2.0 AJAX Extensions is indeed a bit of a mouthful. Overtime all of this will just be built-in to the core ASP.NET setup. So I suspect a lot of people will just use "ASP.NET" to describe it all.

[...]

[more]

On the naming of products

Thu, 17 Aug 2006 12:19:12 GMT

We just finished another spasm of product naming around here. Like everyone else, we work at developing products long, long before they ever have an official name, so we use code names. After many machinations and much work by marketing and legal and whoever, an official product name emerges. (People often find our official product names a lot less interesting than the code name, witness Origami vs. Ultra-Mobile PC.)

Update Perusing Jeff Atwood's Vertigo blog, I see that he's addressed this question also, and includes links to lists of Microsoft and Apple project code names.

Groups with continuity in their development effort often use themed code names. Around here we worked on "Everett" (Visual Studio 2003) and "Whidbey" (Visual Studio 2005). Next up is "Orcas" (Visual Studio Next) and "Hawaii" (Visual Studio After-Next). The play here is on the geography of Western Washington State and beyond. ("Everett" came about as being "on the road to Whidbey.")

[more]

Fun technical writing

Sun, 06 Aug 2006 09:39:25 GMT

I was chatting with one of my writers the other day, who suggested that writers feel thwarted by corporate standards for technical writing. People would rather read a blog entry than a page on MSDN, he said. The writers -- or this writer, anyway -- yearn to write "friendly" documentation that sounds more like blog entries and less like, uh, documentation. As he put it, they want to write docs that have a little more personality.

Everyone knows that after legal documents and government publications, technical writing is about the driest kind of reading there is.[1] Who hasn't heard (perhaps said) "I read this stuff when I have insomnia!" And it's not exactly a challenge to find a piece of technical writing that isn't just boring, but outright incomprehensible, even to people who should know what it's talking about.

It's not as if technical writing can't have personality. Anyone who's dabbled in Ruby knows about why's (poignant) guide to Ruby and its famous cartoon foxes. In "a funny manual that works," Gordon Meyer recently noted that "it's very difficult to use humor effectively in technical documentation," but he calls out some examples by David Pogue and Bill Bumgarner where he thinks they've done the trick. I have my own favorites. As I've noted before, a book that had a big influence on me is John Muir's classic How to Keep Your Volkswagen Alive ... A Manual of Step by Step Instructions for the Compleat Idiot [more]

MSDN changes

Thu, 13 Jul 2006 09:58:07 GMT

The advantage of MSDN is that it consolidates all the developer documentation from Microsoft into a single library -- if it's a released developer product, you'll find (should find?) the docs for it there. Awesome.

The problem, however, is that MSDN can be ... hmmm, how to phrase this? ... a teeny bit unwieldy. Like, you know the docs you're looking for are there ... somewhere. And there are the occasional, you know, surprises. Did you know, for example, that all the ASP.NET 2.0 docs are not in www.msdn.com but actually in www.msdn2.com? This isn't so much a problem if you use, uh, certain search strategies to get at the docs, but let's face it, there are two libraries.

Welp, the MSDN folks are on the job. They posted a note recently on their home page advising readers about the existing of that whole 'nuther library. But more to the point, as they say, "In the coming months, the documentation hosted in both libraries will be consolidated into a single MSDN Library." Yay for that.

Managing a site as large as MSDN is quite a challenge, no doubt about it. We see it from both ends, as content providers to that site and, like everyone else, as users, so we're maybe even more eager than ordinary folks to see these improvements. :-)

PS Don't forget the MSDN Devwiki!

Don't piss off a linguist

Tue, 11 Jul 2006 00:14:38 GMT

Renowned linguist Geoffrey Pullum fumes about something we all know a great deal about, namely dialog boxes that are confusing. In his case, the dialog box says this, apparently:

Mail has been updated. Do you want to allow the new version to access the same keychain items (such as passwords) as the previous version?

This change is permanent and affects all keychain items used by Mail.

[Don't Change] [Change All]

Pullum asks the obvious question: "Which of those is supposed to mean 'Yes, allow the new version access to the old passwords', and which is 'No, I have changed my mind about this, don't allow access?'?"

Pullum then makes what seems like a slightly odd observation here: "Let me add that the operating system that has done this to me is OS X, running on my Apple Macintosh G4 notebook computer — superb software running on a marvellous machine. It is just astounding that anyone uses Windows machines at all anymore, given that both OS X and Linux are of such overwhelmingly superior quality."

Do I follow this right? OS X presents a terrible error message, and it's amazing that people still use Windows?

Anyway, he closes with this statement, at which I shall choose to take personal affront, whaddya think?

It appears that in software development divisions there is typically no one technically trained in syntax, semantics, and pragmatics overseeing the choice of language in the dialog boxes and help panels that are written. The problem is that in most software divisions, the team has no linguist (or linguistically sophisticated technical writer — the degrees held matter less for this purpose than the linguistic acumen)[1].

[more]

On error messages

Fri, 07 Jul 2006 12:40:02 GMT

The ever-interesting Eric Lippert has a thoughtful post on how to create good error messages. His particular focus is on the error messages generated by a compiler, but there's very little in there, save perhaps the actual examples, that wouldn't apply to most situations.

His thesis in a nutshell is that error messages should be:

Polite
Readable
Accurate
Precise
Diagnostic but not prescriptive

... and I'll refer you to his post for the definitions and distinctions of these and for examples.

The last one, as he predicts, is probably the one that is likeliest to be debated by error message authors. The problem with being prescriptive, of course, is that you don't necessarily know what the user is doing, so it can be hard to tell them what to fix. For that matter, in many contexts you don't necessarily know what the problem is exactly; you might just know that something has gone awry. A classic example of this last is the error message you might sometimes see:

The type or namespace name 'some name' could not be found (are you missing a using directive or an assembly reference?)

I like this because it's diagnostic -- the message tells you exactly what the compiler doesn't recognize. But it's also ... well, not prescriptive, exactly, but, you know, helpful -- "People who see this message often see it because xxxx!" That is, it points you at what is probably the most common source of this error without telling you that that's your problem.[1]

Of course, no error message is any good if people don't read it at all. As Leon recently pointed out [more]

Don't like our docs? Amend them!

Fri, 09 Jun 2006 01:51:37 GMT

Not to belabor news that's been published elsewhere, but we rolled out a new thing (in beta) today -- a wiki-like "community content" version of MSDN topics:

http://msdnwiki.microsoft.com/en-us/mtpswiki/default.aspx

This is not a wiki in the Wikipedia, anyone-can-edit-anything sense. As Rob Caron points out, it's "more of a companion wiki to the existing product documentation. It allows you to contribute blocks of content for each existing help topic."

So if you take exception to, say, one of our code examples, you can't just go in there and change it to your liking. But you can add content that could include your opinion ("This is terrible! And here's why ...") and/or put up your own, much improved example.

Although the original doc content is locked, the user commentary is not, and in true(r) wiki style you can edit others' contributions. (The stuff is versioned.)

I had a go during our internal test period. (Here's one example.) I had been slightly worried about the UI, but it was straightforward enough to use.

One thing I noticed when I was doing some test posts is that at that time it was kind of lonely out there, seemingly all by myself. (Naturally there were other people testing, but MSDN is vast and only a very small percentage of topics had community content added at first.) Like any kind of social software, a wiki benefits from the network effect [more]

Folding instructions

Sun, 23 Apr 2006 15:00:05 GMT

In the latest A.Word.A.Day AWADMAil roundup of user comments, someone linked to the Web site of Robert Lang, an origami master. And I do mean "master"; go have a look at what the guy has done, omg.

The guy obviously thinks Deep Thoughts about origami. One of the items on his Web site is an article he wrote not about how to create specific origami figures, but about how to write instructions ("diagramming") for origami figures. I don't know why exactly I glanced through this, but I did, and as I read it, I realized that almost all the conventions he proposes are equally applicable to our work, or at least the part of it that concerns step-by-step instructions. In fact, his advice is probably generic to any procedural documentation.

Herewith some of his proposals:

Be consistent with the past. The takeaway here is to respect what readers already know; don't make up some new conventions that they'll have to learn in order to understand your instructions.
Be grammatically correct. By which he means that you should use words consistently; the same elements are always described the same way.
Make the drawings/text stand alone. What if your reader can't see the diagrams, for instance? A picture is worth a thousand words, but you probably still need to write those thousand words.
Don't leave the reader dangling. [more]

Top jobs

Thu, 20 Apr 2006 13:58:31 GMT

Here's something that's making the rounds today at work: Money Magazine's "Best Jobs in America" list. Top job: software engineer.

What grabbed our attention was technical writer (#13) and and editor (#19).

Per the magazine, the criteria include, among others: pay (duh); projected growth; stress level; creativity; and job flexibility.

Nice to know that one has what's considered to be a good job.

Anniversary

Fri, 24 Mar 2006 10:27:48 GMT

Nine years today at the big M. Plus a year and a half of contracting before that. Time sure does fly by ...

Three on editing

Fri, 17 Mar 2006 01:14:30 GMT

Further observations on the editing life.[1]

1) I was talking at work the other day to someone I hadn't seen in a while. She asked why she hadn't seen me around with the writers, and I told her I'd switched over to editing. "Oh," she said. "I didn't know there was any difference."

2) I've been editing documents written by some program managers and testers. I finished those last week, but I noticed yesterday that one of the files had all sorts of wacky typos and errors in it. I tracked down the tester who had made the changes and explained that I'd already finished editing that document. "I didn't change anything you edited," he told me. "I just added some new stuff."

3) This from John McIntyre's column at the Baltimore Sun:

Copy editors have a deeply Augustinian perspective on human experience: We know that everyone is fundamentally prone to error. That gives us a degree of confidence in our job security, but it also haunts us that we are as disposed to go astray as everyone else.

[1] Even though Leon apparently finds these self-indulgent.

Missing sample code

Thu, 09 Mar 2006 16:54:24 GMT

When you read a page on MSDN, you can both rate it and enter comments. Other people can see the ratings, but the comments are not visible to all.

Now and again we'll have a look at a topic and wonder about the ratings. (Well, we generally wonder only about bad ratings. :-) ) There have been a few that we thought were pretty useful topics that have gotten low ratings. Then when we look at the comments, we'll find out that, oh, say, the code in the topic has a bug in it. There's a way to get yerself a low rating.

And do you want a really, really low rating? How about if you leave the sample code out altogether? Uh ... oops. We did this in a topic I was looking at today[1]:

How to: Locate the Web Forms Controls on a Page by Walking the Controls Collection

The comments were surprisingly un-vicious, considering. Anyway, here's the missing code:

' VB
<%@ Page Language="VB"  %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >

<head runat="server">
    <title>Locate the Web Forms Controls on a Page by Walking the Controls Collection</title>
</head>

<script runat="server">
    Private Sub Button1_Click(ByVal sender As System.Object, _
     ByVal e As System.EventArgs) Handles Button1.Click
        Dim allTextBoxValues As String = ""
        Dim c As Control
        Dim childc As Control
        For Each c In Page.Controls
            For Each childc In c.Controls
                If TypeOf childc Is TextBox Then
                    allTextBoxValues &= CType(childc, TextBox).Text & ","
                End If
            Next
        Next
        If allTextBoxValues <> "" Then
            Label1.Text = allTextBoxValues
        End If
 [more]

Vista tone

Wed, 09 Nov 2005 21:44:34 GMT

Looking at an article from Mike Gunderloy ("Everything You Know About UI Design Is Wrong") got me to download the Microsoft Vista User Experience guidelines. What interests me most at the moment, not surprisingly, are the guidelines for creating UI text.

The fact that there are quasi-official guidelines for creating UI text is itself interesting. I might be horribly mistaken here, but I don't know that MS published anything official-like about how to write your captions and error messages. They even have a name for it: The Microsoft® Windows Vista™ tone.

For anyone who's paid much attention to issues of UI text, many the guidelines are not surprising. For that matter, if you've ever read an article on writing clearly, the suggestions will sound quite familiar. Not that this is a negative; on the contrary, telling UI text writers explicitly to address the user as you, use the active voice, "omit needless adverbs" (to slightly misquote Strunk & White), etc, is all good.

There are more abstract guidelines than just good grammar, though. The guidelines try in various ways (sometimes explicitly) to encourage writing that sounds like a real person: avoid words you wouldn’t say to someone else in person. Or be polite, supportive, and encouraging. These suggestions are illustrated with examples that show correct/incorrect and acceptable/better.

There are some suggestions that to me as a doc writer would take some getting used to, because they're not in the style we've had drummed into us. For example, they encourage contractions, which are stricly verboten in our docs (though not at Microsoft Press; I don't know MSDN's policy). They have some guidelines for using two words you'll never find in our docs today: we and [more]

Petzold on VS

Mon, 24 Oct 2005 15:42:09 GMT
Does Visual Studio rot the mind? asks Charles Petzold. Petzold writes what is not a screed/rant, really, just why he thinks Visual Studio ... let's say encourages people to write code in particular ways. Not necessarily the way he would code in an ideal world. In fact, as he notes, when he teaches Windows Forms programming, he has people start not with a Windows Forms application, but with an Empty application, so that he can build up, manually and deliberately, the code that VS ordinarily spits into the template.

There are many interesting points in his speech, and I won't try to capture them all here. I will note that many points he's talking concern Visual Studio 2003, and that some of what he's talking about has changed in Visual Studio 2005. But he also addresses himself to some new aspects in 2.0, particular design-time XAML.

However, I will quote some statistics that he provides on the size of the APIs in .NET. This is particularly interesting to us -- we writers and editors -- because we have to have documentation for every one of these:
Tabulating only MSCORLIB.DLL and those assemblies that begin with the word System, we have over 5,000 public classes that include over 45,000 public methods and 15,000 public properties, not counting those methods and properties that are inherited and not overridden. A book that simply listed the names, return values, and arguments of these methods and properties, one per line, would be about a thousand pages long.

If you wrote each of those 60,000 properties and methods on a 3-by-5 index card with a little description of what it did, you’d have a stack that totaled 40 feet. These 60,000 cards, laid out end to end — the five inch end, not the three inch end — can encircle Central Park (almost), and I hear this will actually be a public art project next summer.
Whew.

[more]