Agile Documentation – Tested to Destruction

Agile development is an important technique here at p&p; and throughout much of Microsoft. However, I’m yet to be convinced that it’s a good way of creating user guidance and documentation. It seems to me that the process often gets in the way more than it helps to produce a great final product. I’ve rambled…


An Upper Case of Indecisive Instruction

A couple of weeks ago I was ruminating on how somebody in our style guidance team here at Microsoft got a new Swiss army knife as a holiday-time gift, and instead of a tool for removing stones from horse’s hooves it has one for removing capital letters and hyphens from documentation. Meanwhile the people in…


It Configures

Some weeks ago, I rambled on for a while about making a use case for scenarios. It came about through an experience working on a project where a specific set of features of the software were so complex and unintuitive when you randomly played with them that it seemed almost impossible to provide potential users…


Agile Government

I was talking with a colleague the other day about how a pre-agreed plan can morph over time so that the final outcome bears almost no relation to the original specification. I tossed into the conversation my opinion that he should think of it as being like a Government election. The truth changes over time,…


Making a Use Case for Scenarios

Technical writers, like wot I am, tend to be relatively docile and unflappable creatures. It comes with the territory (and, often, with age). Especially when most of your life is spent trying to document something that the dev team are still building, and particularly so if that dev team is resolutely following the agile path….


Can Writers Dance The Agile?

It’s probably safe to say that only a very limited number of the few people who stroll past my blog each week were fans of the Bonzo Dog Doo Dah Band. Or even, while they might recall their 1968 hit single “I’m the Urban Spaceman” (which, I read somewhere, was produced by Paul McCartney under the…


Agile Development in the Bricks and Mortar World

It’s a strange experience when you open the curtains in the morning to be faced by men in high visibility jackets and hard hats only a few yards away, and 30 feet above the ground. Mind you, the noise made by the assortment of cranes, diggers, and other plant they use – combined with regular…


Measuring Job Satisfaction

Listening to the radio one day this week, I heard somebody describe golf as being “a series of tragedies obscured by the occasional miracle”. It struck me that maybe what I do every day is very similar. If, as a writer, you measured success as a ratio between the number of words you write and…


Am I Done Yet…?

I’ve been trying something new and exciting this week. OK, so it’s perhaps not as exciting as bungee jumping or white-water rafting, but it’s certainly something I’ve not tried before. I’m experimenting to see if I can use Team Foundation Server (TFS) to monitor and control the documentation work for my current project. As usual,…


In Search Of The Missing Link

Every now and then I get to write actual code rather than just documentation. Usually there’s either a crowd watching in amazement that I can actually find Visual Studio, never mind knowing some of the magic keywords that make it all work when you press the green arrow button. Or else everyone is cowering behind…