Writing ... or Just Practicing?

Random Disconnected Diatribes of a p&p Documentation Engineer

  • Blog Post: General Cluster's Probably Not Last Stand

    I don't know if General Custer ever made a last stand against the Apache, but I feel like I have. My Apache is, of course, the Hadoop one. Or, to be technically accurate, Microsoft Azure HDInsight. And, going on experience so far, this is unlikely to actually be the last time I do it. After six months...
  • Blog Post: Defensive Writing

    One of the facts of life when you write technical documentation and guidance is that it will get reviewed by other people, resulting in regular changes to the content as you try to follow shifting advice, conflicting feedback, and suggestions that sometimes even make sense. It doesn't help, of course...
  • Blog Post: my data are getting littler

    It looks like our Big Data is getting smaller. At least that's the impression I get from the exhaustive investigation carried out by the editor on our current project. Of course, "data" is actually a plural word so perhaps it's just that each datum is getting smaller. Or maybe there are fewer (not "less...
  • Blog Post: I Can See Patterns In The Cloud

    Well, we finally did it. After many months of redesign, reconsideration, rewrites, and recombination we've let loose on the web our first release of the Cloud Design Patterns guide. The guide is a combination of design patterns that are especially applicable to cloud-hosted applications and services...
  • Blog Post: Gimmie The Code!

    It seems like a question that has an obvious answer: How should you show code listings in guidance documents? I'm not talking about the C#/VB/other language debate, or whether you orient it in landscape mode to avoid breaking long lines. No, I'm talking about the really important topics such as what...
  • Blog Post: 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....
  • Blog Post: A Cloud Service By Any Other Name...

    As a firm believer in freedom of expression, I guess I can't complain about the names that the Windows Azure team give to their services and features. After all, my responsibility is just to write about them. In theory that can call them whatever they like. The problem is that they keep calling things...
  • Blog Post: Over-egging the Curator's View

    At one time you had to work in a museum to be a curator, but the wonders of information technology mean that now we can all exhibit our technical grasp of complicated topics and elucidate the general population by identifying the optimum resources that help to answer even the most complex of questions...
  • Blog Post: Big Data, Big Guidance Problem

    You'd think that, after all the years I've been writing guidance for Microsoft technologies and tools, I'd have at least grasped how to organize the structure of a guide ready to start pouring content into it. But, just as we're getting into our stride on the Windows Azure HDInsight project here at p&p...
  • Blog Post: Is it a Scenario? Is it a Case Study? No, it's an Opportunity

    A few influential people in our little world of Developer Guidance here are Microsoft have recently been avoiding the word "scenario". It seems that it's now so overused, and has so many apocryphal meanings, as to render it useless in terms of determining user's documentation requirements and for planning...
  • Blog Post: Just Press F1!

    I'm increasingly seeing how big the disconnect is between people who use computers occasionally just because they need to do stuff on the Internet, and those of us who live and breathe computing. And we're not talking stupid people here; I see it most weeks with friends and acquaintances that are fully...
  • Blog Post: What Color Is Your Field?

    So, at last, we're done. After fighting with multiple new versions of the Windows Azure SDK, updated features in the management portal, changes to the functionality of services, and the regular changes to the names of various parts of Windows Azure, we've shipped the third editions of two of our Windows...
  • Blog Post: A Prolonged Burst of Frenetic Procrastination

    Following a discussion last week about how the most successful national clubs and societies have evolved, I was amused by a response from someone who professed to setting up the National Procrastination Society. He reckons that this is the most successful society ever because none of the members has...
  • Blog Post: A Relentless Paper Chase (aka Painting Windows Azure)

    Here in Britain we always used to refer to a job that was never-ending as "like painting the Forth Bridge." It came about because the people who paint the huge and magnificent railway bridge over the Firth of Forth in Scotland reportedly start at one end and it takes so long that, when they reach the...
  • Blog Post: 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...
  • Blog Post: Web Sites or Cloud Services?

    The latest update to the range of Windows Azure services includes a nifty feature called Web Sites that provides a really great way to deploy your own websites to the cloud. It's quick and easy, you can progressively update the site by uploading individual files, and it's cheap. In fact at the moment...
  • Blog Post: Hyphenless Decapitalization

    According to Readers Digest, there's a dyslexic agnostic insomniac out there somewhere who lies awake all night pondering on the meaning of dog. Thing is, it really should be "doG", not "dog". But it seems that, according to our most recent style guide here at Microsoft, capital letters are fast becoming...
  • Blog Post: Hands-Off Labs

    It seems to be a general rule now here at p&p that every guide we produce must have an associated set of practical examples so that users can get their hands (and keyboards) dirty playing with the technologies. It's almost like we're worried that our readers won’t believe the stuff actually...
  • Blog Post: It Feels Like I've Been Snookered

    Probably the most memorable comment from a snooker commentator was Ted Lowe during a Pot Black match in the late 1960s. Acknowledging the fact that in those days many viewers didn't have a color television, he helpfully noted "for those of you watching in black and white, the pink ball is next to the...
  • Blog Post: The Rule of "It Depends"

    It seems odd that, in order for a rule to be valid, there has to be an exception. According to the well-known phrase "the exception that proves the rule", this must be the case. Yet watching a TV quiz show the other week, I was amazed to discover that one of the rules I've applied most days of my working...
  • Blog Post: Hybrigation Complete, Feedback Required...

    So at last we've finished the Windows Azure hybrid applications guide , and it's out there ready for anyone interested in integrating cloud-hosted applications with on-premises services and partner applications. OK, so it's taken a little longer than originally planned but it is more comprehensive than...
  • Blog Post: Writing? It's Easy...

    I've decided that, next time I write a book, I'm going to put everything on page one and make some obvious errors as well. I'm not convinced that it will actually do much to make the book any better, but it will save the reviewers a lot of headaches. And probably make it easier for the publisher too...
  • Blog Post: What's The Point?

    My wife will tell you that I'm really not very good at getting the point of things. I mean, when it comes to making typically vital choices such as whether I want brown sauce or ketchup on my sausage sandwiches, I can't see the point of long-winded pondering and tortuous decision making. Just put brown...
  • Blog Post: An Enduring Documentational Experience

    Unless you write books or guidance for long-lived technologies, such as assembly code programming or software design patterns, the products of your IT documentational effort tend to have a somewhat limited shelf life. There's always a new version of ASP.NET, Linux, J2EE, or C# just around the corner...
  • Blog Post: The (Non-political) Third Way

    One of the major advances in politics in recent years has been the evolution of “The Third Way”. You know the kind of thing: Given a choice between two approaches to a problem, neither of which are politically palatable, politicians invent a “third way” that relieves them of the...
Page 1 of 3 (72 items) 123

Browse by Tags