Writing ... or Just Practicing?

Random Disconnected Diatribes of a p&p Documentation Engineer

  • Writing ... or Just Practicing?

    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, ready to be released into the wild a month or so after you finish your latest magnum opus. I know this only too well from eight years of writing books about Active Server Pages and ASP.NET.

    However, compared to the real heroes in the writing world, eight years is but a blink of the eye. I can remember as a teenager watching some early episodes of a program called Last of the Summer Wine with my parents, and struggling to see the point of it. Three old men wandering around amidst beautiful scenery wasn't my idea of a sitcom. Yet now, some 40 years later, I'm watching it all over again.

    Last of the Summer Wine (LOTSW) began with a trial series in 1973, and was such a hit that it continued until the final episode in August 2010, becoming the longest running sitcom in the world. But after 37 years, 31 series, and 295 episodes, it is no more. Yet, thanks to the wonders of multi-channel digital TV, we can now watch most of the episodes all over again. And I can't get enough.

    It's hard to say what it is about the program that keeps bringing me back to watch more of the old episodes. It's not that it was hilariously funny, amazingly fast and sharp, or had the international appeal of Friends, Frasier, and The Big Bang Theory. Nor was it focused on a single character, such as Lucille Ball or Captain Bilko. And the broad popularity of LOTSW means it can't just be that it appeals to my strange sense of humour. For example, when Compo asked Cleggie what a "trice" is (after Seymour mentioned that their latest problem would be "over in a trice") Cleggie's answer was "Well it's like a jiffy, but with three wheels."

    Perhaps it's the wonderful scenery - the on-location filming around Holmfirth in Yorkshire is beautifully done; and especially interesting if you've been there and seen the town and countryside around it. Or is it the amazing combination of strange but believable characters that seem to turn the observations of ordinary life into a wonderfully gentle comedy of errors. And there must be some other underlying effect that lulls you into a sense of calm and satisfied appreciation. I suspect it's the lilting guitars and harmonica of the theme tune and incidental music, or recognizing how your Mother also used to put newspapers on the kitchen floor when you came in from outside. Or remembering that (like Compo) your grandfather tended to drink his tea out of the saucer.

    For me, though, there's also the poignancy provided by Peter Sallis who bears a remarkable likeness in appearance and manner to my late father. Peter played the lead part of Norman Clegg, and was the only one of the three main characters to have been in all of the episodes. He was a well-respected actor long before Last of the Summer Wine, of course, but is now best known for his "Cleggie". Though you'll probably know his voice if not his face - he is Wallace in the Wallace and Grommit films.

    I suppose what prompted all this was watching a documentary about the series this week, featuring the writer Roy Clark. Roy wrote every episode over the 37 years as they filmed on location in summer and then in the studios during the winter. He wrote around changes in the characters as famous faces joined and well-known members passed on, even replacing two of the three lead actors (one several times). Yet none of the changes seemed odd or forced; somehow it all just worked, year after year.

    But the point is, how would most IT documentation engineers cope with writing follow-on guidance and updates for a product that changed every year for 37 years? I'd be on ASP.NET v34.0 by now, still wondering how to describe the latest implementation of the Request collections, or document the new features available in output caching. It's hard to see how I would maintain my focus, my interest, and even my sanity.

    Mind you, at the rate that Windows Azure is evolving, we'll probably be on version 37.0 sometime next year...

  • Writing ... or Just Practicing?

    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 requirement to choose either of the two undesirable outcomes. Of course, in reality, there are only two realistic options, and “the third way” usually involves doing nothing that resolves the issue or makes any real difference.

    However, in the real world where we IT documentation engineers live, it seems there is a third way that actually does resolve the problem of a choice between two seemingly incompatible and undesirable options. In fact, in our current project, we’ve taken advantage of this ground-breaking technique in an effort to provide better guidance to our readers.

    Faced with the requirement to create guidance around Windows Azure hybrid application integration (a topic I’m resolutely attempting to get recognized as “hybrigation”), we examined the two obvious approaches. We could base the guidance on the actual technologies available and used in the sample application that accompanies the guidance, or we could make the guidance more generic and useful by focusing on segregated categories of the challenges encountered in hybrigation using a series of generic scenarios.

    My regular reader will know that I’m a fan of scenario-base guidance that addresses the widest audience, and guides readers towards the most suitable technological choices based on requirements, tradeoffs, and constraints. In other words, we take a common problem area such as communicating between an Azure-hosted application and an on-premises application, and research the individual scenarios based on typical requirements and hardware / software / environmental constraints. For each typical scenario, we describe the appropriate technologies and enumerate the advantages and limitations of each one so that readers can choose the most optimal solution for their own situation.

    However, this approach may not take full advantage of the sample application that the development guys sweated blood creating. So we add some explanation of how parts of the scenarios previously described are implemented in the sample. But that only demonstrates a few of them, and these may not be the ones most applicable to the readers’ own situation and requirements.

    The other option is to align the guidance with the sample implementation, and base the contents on explaining how it was designed and built. This is perfect for readers who want to build the same type of application that uses the same technologies and runs under the same hardware / software / environmental constraints; which is, of course, unlikely. But there are reusable chunks of code in there, so it is of value to a proportion of readers that need to tackle similar challenges.

    Somebody famous once (nearly) said “You can teach all of the people some of the time, or some of the people all of the time, but you can’t teach all of the people all of the time.” It seems to be true, but only until you discover “the third way.” What is it? Well, dead easy really. You just do both. Explain how the sample application works, but include in the description the options that the application designer considered, the range of technologies that are available, and why they chose the approach they did. Then show how they implemented the chosen approach.

    Ah, you say, but where did the generic scenarios go? Well, you can segregate the description of the application design and implementation into the different challenges, such as cross-boundary communication or data synchronization. And then tag onto the end of the guidance a set of appendices that investigate a wider range of general scenarios for each of these challenges. Readers can use the first part of the guidance to understand the design process of the sample application and the choices this involved, but also read the more comprehensive list of general challenges and scenarios to find solutions and advice more closely tailored to their own environment and requirements.

    So readers get the best of both approaches. They learn more about both the design and the implementation of the sample, and also the other solutions that are applicable under different conditions. The only trouble is that we documentation engineers have to do twice as much work. But I suppose it keeps me from having too much spare time for writing rambling and semi-coherent blog posts. Or from continually inventing new words...

  • Writing ... or Just Practicing?

    That What Was Demonstrated


    It's been a long time since I studied particle physics in my spare time at university. However, as it looks like the clever people at CERN will soon be publishing photos of their new baby - the delightfully named Higgs Boson - I thought I ought to get caught up with some background theory so that I will be ready to fully appreciate the revelations around their new arrival.

    I can remember being enthralled learning about the discovery of quarks, with their wonderful properties of charm, beauty, and (best of all) strangeness. And I still haven't figured out why they thought that changing the name of the "beauty" quark to "bottom" quark was a good idea. Maybe they just needed something to counter the "top" quark. But it's the Higgs that is the focus of interest now; and it may even provide the answers to all those questions about life, the universe, and everything. In particular, it will tell us why things are heavy. And, maybe, why we are here at all.

    See, that's the odd part. For years physicists have been telling us that there isn't enough matter in the Universe; supposedly 75% of it is missing and has to be accounted for as the mysterious "dark matter" that astronomers keep saying they've seen fleeting glimpses of, but nobody can really figure out what it is and whether these astronomers are just making it up as they go along.

    Yet now, as we seek the furtive and enigmatic Higgs particle, the same physicists are telling us that there's actually too much matter in the Universe. In theory the Big Bang should have generated equal amounts of matter and anti-matter, and these should have spontaneously annihilated each other so there was nothing left. Supposedly we're only here because of the Higgs making some stuff a bit heavier and clumpy during the first few minutes of creation. Mind you, heavy and clumpy is a pretty neat description of my aging physique these days - maybe I somehow got an extra dose of Higgs in the past.

    So, anyway, over the last few weeks I've accumulated a small pile of (thankfully math-free) books on the general topics around what is now call Quantum Electrodynamics, or QED. This clever use of abbreviations (from the Latin "Quod Erat Demonstrandum", meaning "which was to be demonstrated") is presumably designed to show that they already know all the answers. Although it turns out that there are a couple of additional theories doing the rounds as well. Quantum Chromodynamics (QCD) suggests that quarks come in three colors; red, green, and blue. Though technically these are just theoretical properties - they don't, it seems, show up in different colors in the photographs.

    And Supersymmetry, usually abbreviated to just "Susy", adds lots of new particles to the possible list. Now there are squarks as well as quarks, selectrons, photinos, sleptons (the ones that are all crinkled), and even winos (probably these are the ones that follow an indeterminate wandering path through the detectors). Presumably there'll be a shiggs particle to hunt for as well.

    But getting back to the books, one of the most fascinating is "The God Particle" by Leon Lederman. Or, as the strapline says, "If The Universe Is The Answer, What Is The Question?" In this book, as well as the history of this area of physics and the underlying scientific theory, Mr. Lederman talks about how they had to cut up an old US warship to get enough metal to surround the particle detector with a five feet thick iron shield. And how the computer geeks in the lab had to create programs that can analyze one megabyte of data arriving from the detector every millionth of a second.

    He also quotes the following wonderful phrase taken from the thesis of one of his students: "This field of physics is so virginal that no human eyeball has ever set foot in it." I've decided that, here at p&p, we should incorporate more of this kind of enlightening phraseology into our guidance. We could start with "The web server will emit HTTP packets like a bullet from a catapult." Or "Initial configuration is as easy as falling off a hot tin roof." And for our current project on Windows Azure hybrigation techniques, how about "Components should fit the architecture like a hand in a pocket, have functional concerns that are as different as chalk and chocolate, and run like a cheater."

    In the meantime, I wonder if some scientists will celebrate the forthcoming breakthrough in physics when naming their offspring. I'm fully expecting to hear of twins called Susy and Higgs Boson quite soon...

  • Writing ... or Just Practicing?

    Hands Up If You're Doing Hybrid...


    After several months of diligent dappling with documentation, comprehensive confrontations with code, and seriously systematic study of system architectures, we've managed to toss together most of the content for our upcoming guide to Windows Azure hybrigation techniques. "Integrating with the Cloud on the Windows Azure Platform" covers all kinds of aspects of hybrid application design and implementation, and we've even got some code to prove it all works.

    So all we need do now is validate the content. We've got some of the finest minds from the individual product teams looking at our guidance and providing valuable technical assistance, but we need people who have used all this stuff in the real world to review it. Architects who have piously pondered over designs, developers who have bravely battled with the technologies, and especially those who have configured, deployed, and managed hybrid applications on Windows Azure.

    If you're feeling brave, have time to spare, are short of bedtime reading materials, or just want to find all the spelling errors we missed, grab a copy of the PDF from http://wag.codeplex.com/releases/view/74838 and tell us what you think. Comments, feedback, suggestions for improvement, and chocolate are all welcome. You might even get your name into the acknowledgements...


  • Writing ... or Just Practicing?

    Leaping To Conclusions - Predictions for Leap Year 2012


    After my resounding success predicting that 2011 would finally see the lingering and painful death of JavaScript, and that the interface of Windows 8 will consist solely of one large Flash animation, it's time to apply my unerringly accurate predictional capabilities to this squeaky clean New Year. So if you aren't quite sure what 2012 holds in store, read on...

    • January: Amazon will have learnt enough about your shopping habits to be able to deliver everything you need each Monday without you even having to place an order. Meanwhile, Google will know enough about you to open a browser with a list of all the web pages you'll need that day before you even get into the office in the morning.

    • February: The scientists at CERN will manage to isolate the Higgs boson, and discover that it is made up of millions of even smaller particles that are suspended in a previously unknown kind of ethereal soup. They'll call these particles "croutons."

    • March: The exponential growth in patent infringement claims against technology companies means that the world will run out of lawyers, and several Governments will be near bankrupted by the cost of training new ones and building hundreds of additional courthouses. Meanwhile, in the face of falling profit margins, Apple will more aggressively enforce its patent on the use of the lower-case letter "i". Ths s lkely to have a huge mpact on the documentaton and gudance provded by other technology companes.

    • April: During a clear out of a forgotten storeroom to digitize the books it contains, a dance instructor in Dublin will discover the long lost book "Irish Country Dancing - Part 2: The Arm Movements". Meanwhile, when Spring-cleaning the members' lounge at the Strasburg headquarters of the European Union, a cleaner will find the 1.3 trillion Euros they misplaced down the side of a sofa.

    • May: The Windows Azure team will stop changing the names of things and the URLs of their web pages long enough for us here at p&p to get at least one guide on Azure development out of the door with all the correct stuff in it.

    • June: Epson will release the first affordable 3D printer to the general public. After a few people buy one and start using it to make 3D printers, all of the printer manufacturers will go out of business.

    • July: Somebody will realize that you can make wind turbines spin by pumping electricity into them, turning them from generators into huge electric fans. The Government will take advantage of this to move Britain nearer to the US and away from the European Union geographically, even though it's not possible politically.

    • August: The new supercomputers at the Meteorological Office in London will make weather forecasting so accurate that that you'll be able to download a list of all the days that will be hot and sunny a year ahead. The Government will immediately introduce a new Sunny House Tax with charges based on a graduated scale, and higher rates for people who own garden chairs or a trampoline. For health and safety reasons, it will be illegal to go outside without an umbrella on days when it will rain.

    • September: Smartphones will have advanced so much that people will discover using Voice Over IP with apps such as Skype, Messenger, and Lync gives much better quality and reliability than ordinary phone calls; and manufacturers will reduce costs by removing the normal phone capabilities. The most desirable devices next Christmas will be the iCantphone 6 and the Windows Notaphone (with the Mango operating system replaced by the new Truly Universal Reliable Network IP Platform (Turnip) operating system). The downside will be when users get their first phone bill and discover that the telephone companies exorbitant data charges make calls more expensive than using the old-fashioned method.

    • October: Physicists in Italy will finally validate the unexpected results of recent experiments that suggest some types of particles can move faster than the speed of light. The McLaren Formula 1 team will use this material to build next year's car, but will be disqualified in the first race because the rules clearly state that all cars must abide by the laws of Special Relativity.

    • November: Users that rushed to adopt the latest generation of tablet and slate computers (known in the trade as "fondleslabs") will come to realize the severe shortcomings of limited battery life, a small screen, and lack of a proper keyboard and mouse. An enterprising peripherals manufacturer will release a new product aimed at just this market. It will consist of a large black box with a slot that accepts any model of tablet computer, has a built-in mains-driven power supply, and sockets on the back for the large screen (with integral adjustable stand), full-sized button-action keyboard, and six-button ergonomically-shaped mouse. It will be called "The Desktop Computer."

    • December: JavaScript will finally endure a lingering and painful death.

    Happy New Year!

Page 1 of 1 (5 items)