Writing ... or Just Practicing?

Random Disconnected Diatribes of a p&p Documentation Engineer

  • Writing ... or Just Practicing?

    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. You know that the features of the software and its capabilities will morph into something completely different just after you get the docs on that bit finished; and they'll discover the bugs, gotchas, and necessary workarounds only after you sent your finely crafted text to edit.

    And you get used to the regular cycle of "What on earth have they added now?", "What is this supposed to do", "Can anyone tell me how it works", and "OK, I see, that must be it". Usually it involves several hours searching through source code, playing with examples, trying to understand the unit tests, and - as a last resort - phoning a friend. But, in most cases, you figure out what's going on, take a wild stab at how customers will use the feature, and then describe it in sufficient detail and in an organized way so that they can understand it.

    Of course, the proper way to document it is to look for the scenario or use case, and describe this using one of the well known formats such as "Scenario", "Problem", "Solution", and "Example". You might even go the whole hog and include "Forces", "Liabilities", and "Considerations" - much like you see software design patterns described. Though, to me at least, this often seems like overkill. I guess we've all seen documents that describe the scenario as "The user wants to retrieve data from a database that has poor response times", the problem as "The database has poor response times and the user wants to retrieve data", and the forces include "A database that has poor response times may impact operation of the application". And then the solution says "Use asynchronous access, stupid!" (though the "stupid" bit is not usually included, just implied).

    Worse still, writing these types of documents takes a lot of effort, especially when you try not to make the reader sound stupid, and may even tend to put people off when compared to a more straightforward style that just explains the reason for a feature, and how to use it. Here at p&p, we tend to document these as "Key Scenarios" - with just a short description of the problem and the solution, followed by an example.

    However, in an attempt to provide more approachable documentation that is easier to read and comprehend, I've tended to wander away from the strict "Key Scenarios" approach. Instead, I've favored breaking down software into features and sub-features, and describing each one starting with an overview of what it does, followed by a summary of the capabilities and links to more detailed topics for each part that describe how to use it. This approach also has the advantage in that it makes coping with the constant churn of agile-developed software much easier. The overview usually doesn't change (much); you can modify the structure, order, and contents of each subtopic; and you can slot new subtopics in without breaking the whole feature section. Only when there are extreme changes in the software (which are not unknown, of course) do you need to rebuild a whole section.

    But increasingly I'm finding that the lack of a more rigid scenario documentation approach is causing problems. Mostly this has to do with the lack of a well documented design and use case created up front, before development of a feature starts. If the use case consists of just "Implement a mechanism for merging configuration settings", you can soon find yourself struggling to provide consistent and useful documentation without having to completely rewrite it several times. You end up guessing why it's there, what it's capabilities are in terms of user requirements, what scenarios it is designed to operate in, and what problems it's supposed to address.

    OK, so the whole idea of agile is that you discover all this though constant contact with the other members of the team, and have easy access to ask questions and get explanations. But it often isn't that simple. For example, during testing of the way that Unity resolves objects, I found I was getting an exception if there was no named mapping in the container for the abstract class or interface I was trying to resolve. The answer was "Yes, Unity will throw an exception when there is no mapping for the type". But, as you probably guessed, this isn't a limitation of Unity (as I, employing my usual ignorance and naivety, assumed it was). Unity will try its best to create an instance of any type you ask for, whether there's a mapping or not. But it throws an exception because, with no mapping, it ends up trying to instantiate an interface or abstract class. Needless to say, furious re-editing of the relevant doc sections ensued.

    Then, just to reinforce my growing concern that maybe my less rigorous approach to feature documentation is not working as well as planned, I came across a set of features that are so complex and unintuitive, and viciously intertwined with each other, that understanding the nuances of the way they work seemed almost impossible. Even the test team, with their appropriate allocation of really clever people, struggled to grasp it all and explain it to mere mortals like me. Yes, I can vaguely appreciate what it does, and even how some of it works. But what is it for?

    This seems to be the root of the issue. There are no documented use cases that describe when or why customers would use this set of features, or what they are designed to achieve. Just a semi-vague one liner that describes what the feature is. Or, to be more accurate, several one liners that describe bits of what the feature is. No explanation of why it's there, why it's useful, and why users might need it. Or part of it. Or some unexplained combination of it. Of course, it is impeccably implemented and works fine (I'm told), and is a valuable addition to the software that a great many users of previous versions asked for.

    But the documentation dilemma also reveals, like some gruesome mythical beast rising from the mire, just how frighteningly easy it is to innocently stray from the well worn path of "proper" documentation techniques. It's only obvious when something like this (the problem not the mythical beast) comes back to bite you. Faced with a set of features that almost seem to defy explanation in terms of "what they are" and "what they do", it does seem like the key scenario approach, with its problem, solution, and example format, really is the way to go.

    If the first step of documenting a feature of a product is to discover and list the key scenarios, you have a platform for understanding the way that the software is designed to be used, and what it was designed to do. If you can't even find the key scenarios before you start writing, never mind accurately document them, the chances are you are never going to produce guidance that properly or accurately describes the usage.

    And maybe, one day, I'll even apply "proper" documentation design patterns to writing blog posts...

  • Writing ... or Just Practicing?

    Weather It's Musical?


    If I told you that my wonderful wife bought me a Vantage Pro 2 for my birthday, you might be thinking I was now spending every afternoon outside polishing a gleaming new custom sports car, or happily installing loads of exciting new applications on a super-fast new computer. Or perhaps even spending my weekends taking flying lessons so we could pop over to the Continent for day trips. Well, not quite. The aforementioned piece of equipment rather worryingly resembles a large black bucket with a propeller sticking out of the top and a small white concertina hanging off the bottom.

    But it is nearly as exciting (well, it is if you are a weather geek). After a couple of failed attempts with cheap personal weather stations (see Living in a Cage), we decided to get something a little more robust and reliable. And, despite me grumbling about US-made technologies that make more noise than a snoring hippo (as in Cum On Feel The Noize), it's actually made in California. Shame I can't provide the same kinds of long hot sunny days it's probably expecting. Still, it is a neat piece of kit - solid and well put together, and (unlike most others) has a useful wireless range. It also has a solar panel to help keep the battery charged - which seems like an obvious idea when you think about it. The remote console is really nice. And, best of all, it comes with a data logger and USB output to a PC. Perfect for us IT-oriented folk.

    Except, as with so many other hardware companies that unwittingly wander into providing software, the PC application is less than optimal in design, functionality, and - more than anything else - appearance. I've moaned about this with other hardware stuff (including Ready for Hibernation). Probably they just put it out to tender and take the lowest quote. Though when you look at some of the home-made weather sites on the Internet, you soon come to the conclusion that weather-watching and an innate sense of design seem to be mutually exclusive tendencies. To protect the guilty, I won't pick out any specific ones... its common knowledge that developers have no sense of style.

    As a result of some Web searching, however, it seems that all of the serious weatherists out there use a piece of "donateware" called Cumulus. So I tried it and, wow, it is terrific! So good that I donated a reasonably generous sum on the grounds that software this good deserves support. It natively integrates with the Vantage station, and has a really neat and attractive UI that shows everything (and more) you could want to see. There's tons of graphs and charts available, it maintains history data and the high/low records, and it's really easy to configure.

    And, best of all, it has built-in Internet support. It dynamically generates a complete Web site based on templates that you can modify; it can post data to well-known world-wide weather aggregation sites; and has support for (almost) real time data refresh. Though I can't help wondering what effect writing the data file to the disk every five seconds will have in terms of MTBF. Hopefully, running a scheduled defrag task weekly will move it around the disk and save it wearing a hole on one place! But I guess the server O/S hits the disk just as hard during its day to day operation.

    Cumulus even have available for download a really nice bolt-on Silverlight interface that you can use with the real-time weather data file, as well as including a Flash widget that works in the standard Web site pages. You can easily expose a useful and attractive weather Web site from your own server or from a Web hosting company (providing you can upload the page updates through FTP). And you can specify the update intervals for all of the operations. So if for some inexplicable reason, while reading one of my weekly half-baked ruminations, you wonder what the weather is like here in this tiny remote outpost of the vast Microsoft empire you can go and see for yourself. Or even marvel at the real time version. And, just to prove that integration with other weather aggregation sites works, check out the PWS Project and, of course, Weather Underground.

    However, to see what you can really do with all the data you collect, you just have to go and listen to the music generated by the Weathersongs Project. They take the data from a weather station and process it into sounds. Listen to the "Autumn rainfall" one as a great example. Mind you, as their weather station is in Wales (the home of the world's greatest male voice choirs), you'd expect it to generate quality music. I doubt if the tuneless weather we get here in cold and windswept Derbyshire could compete.

  • Writing ... or Just Practicing?

    What's In Your Sandwich?


    One of the most amazing things about being in the US is the unending choice of stuff - everywhere. And that fact that everything seems to consist of all kinds of other things. Waiters in restaurants (except for the very high class ones) look at you gone out if you try to order a steak without three different kinds of stuffing inside and two sauces on top, not to mention the choice of five dressings for the side salad you don't want, and a selection from the option of six different kinds of potatoes.

    I can't imagine what Americans must think when they come to England. If you go into our local restaurant at lunchtime on a Sunday, they don't even ask you what you want - they just bring you beef and whatever vegetables and other accompaniments they decided to cook that week. Or, if you profess vegetarian tendencies, a nut and mushroom quiche. And, of course, chips (the proper English kind - not anything French, or flat disks of fried potato flour).

    OK, so maybe I'm exaggerating just a smidgeon here. And I've raved in the past about how hard it is to order something simple such as a coffee or a sandwich (see How p&p Makes Cheese Sandwiches). But, since then, I've been able to experience first-hand the competitive nature of sandwich ordering that prevails in many US locations - including the "fancy new building 37 cafeteria" mentioned in that post.

    After choosing the type of bread you want (I don't know the proper names, so I just have to ask for "that flat one"), you select from a range of over 30 different fillings. The lady behind the counter just keeps piling them on, without ever seeming to question the culinary combination and it's possible after-effects, or applying any limit to the number of selections you make. I tend to stop when the sandwich reaches a thickness that, after suitable squidging in the grill and afterwards by hand, roughly equates to the cross-sectional area of my mouth. But plenty of people appear to disregard this rule of thumb, and I'm convinced engage in a competition to see how tall they can make their sandwich before it won't actually fit in the Panini grill.

    Mind you, during my most recent on-site visit, I was relieved of the taxing sandwich assembly choice process one day when they ordered in a load of pre-packed sandwiches so we could continue a meeting over lunch. As expected, most of them were combinations of esoteric (and often, as far as I could tell, extraordinarily mismatched) fillings. I managed to find one with a mixture that seemed logical and reasonably harmless, grilled chicken and mozzarella. However, on reading the packet, I was stunned to discover that even this relatively unexciting delicacy contained some thirty plus different ingredients (as you can see here).

    Of course, that just started another competition - whose sandwich had the largest number of ingredients? After some frantic discussions and investigation, we found one that had 47 different ingredients. A clear winner (and, unfortunately, I can't remember now what it was advertised as). And, of course, all this activity totally disrupted the meeting, and pretty much negated the whole advantage of ordering in.

    Next time, I reckon I'll just order a cheeseburger. I'm sure there's only a couple of simple and wholesome ingredients in them...

  • Writing ... or Just Practicing?

    Location Dependent Narrative


    Perhaps it's just anecdotal evidence, but it seems like you often hear about people who are afraid of the countryside. For those of us brought up amongst fields, trees, and wildlife, this seems an extraordinary concept; though I guess - as I have a deep-rooted fear of cities - the converse is not as unlikely as you might imagine. Personally, I hate the bustle, noise, and smell of city centres such as London and Birmingham, and I can't imagine living in the midst of a constant rush of people, cars, and trucks; and the torrid sense of panic that life in general seems to require in these kinds of places.

    So it was refreshing to be reminded by a TV documentary the other week about the life of Roger Deakin, who wrote about the wildness and beauty of the English countryside in Suffolk and Essex. He died in 2006, but others (including Robert Macfarlane in the recent documentary) have continued his work, showing how even the most industrially despoiled landscapes and man-made ugliness slowly convert back to nature. One thing I found interesting was how Roger worked from many different locations when writing. He collected a range of wheeled "sheds", such as old railway wagons and carts, and parked them in different areas of his farm so that he could live and write in each one, depending on the season and the surroundings as they changed throughout the year. He said the style of his writing varied to reflect the features of each location, allowing him to change his view of topics and document them in different ways.

    It struck me how I, like many writers, tend to do much the same. OK, so I haven't adopted the local café as a base for writing adventures about a boy wizard, and I can't afford to go off and live in Madeira or the South of France for a year, but it does seem as though - despite establishing a fully-fitted modern office with all the things you might need to be an author - I still exhibit itinerant tendencies, depending on the type and content of the material I am charged to create. Certainly at this time of year, with snow lying and a distinct chill in the air, the centrally heated office is my usual home. However, in warmer seasons, I tend to migrate into the conservatory - usefully equipped with a desk, power, and a network socket; and a glorious view of the garden, the fishpond, the birdfeeders, and a small copse of trees. And, at various times, I find myself in the lounge writing with a laptop on my - err - lap, or sitting at the dining table, or even standing next to the server cabinet during those "not really at work but working" moments.

    And it seems that I do create different types of verbiage depending on the location. For many tasks, such as editing post review documents, creating schematics, teleconferencing, and writing and debugging code, I take advantage of the power of the big box and the screen space of two decent sized monitors in the upstairs office. And the view across the fields from this elevated location does make it a pleasant place to work at any time of year. In fact, most evenings find me wired to this machine through headphones for the conference calls and meetings that take place in US Pacific Coast Time mornings.

    But somehow, as the winter wears on, I can't wait to escape from the confines of the office, the random music stream from my media server, and the anti-SAD daylight lamp, into the warmth and brightness of the conservatory. It's probably as near as you can get to working outdoors without actually being outside. There's something special about the sun streaming in, the noise of water and fish splashing in the pond, the birdsong, and the occasional visit from a squirrel (or even, in the late afternoon, a vixen out early searching for food for her hungry cubs). And it's here that I find I can so much more easily write those more lyrical sections of content, such as technology overviews, chapter intros, articles, and my seemingly endless stream of rambling blog posts.

    Then there's the times I need short, sharp, to the point content. A good location for this is ensconced on the sofa in the lounge, or perched on the edge of a chair at the dining table, as my wife watches East Enders or Casualty on TV. The almost constant yelling and screaming (from the TV, not my wife) seems to suit this kind of writing - keeping it tense and to the point. Though it does tend to need additional editing after I calm down again.

    And then there's those "in-between" times when I just need to check my email or send a quick note. The server cabinet includes a machine that runs a locked-down Windows 7 installation where I can administer the virtual servers and network devices, and do general administrative fiddling when required. It's a perfect location for doing email and making brief notes because (a) I'm standing up, (b) it's cold in winter, and (c) I have to use Notepad to write stuff. It keeps me focused on the job in hand, and tends to concentrate the mind into producing concise output.

    The one place I find I cannot write, in a way that produces anything near to useful, is when I'm on site in the team room with all of my colleagues - as experienced in my recent trip across to Redmond. OK, so a constant stream of meetings doesn't help, but even when there are a couple of hours to sit down and get stuck in I find I'm struggling to concentrate. It seems like my head is full of extraneous distractions and the words just won't come. If this is an agile, writer in the room, close to the dev team process, I certainly need some serious practice to cope with it.

    Maybe, unconsciously, I relate it to my fear of cities - and the accompanying torrid sense of panic. The only saving grace is that the corresponding requirement to complete the necessary work in my hotel room in the evenings means that I don't actually have to watch US television programs. Not that they allow you to concentrate anyway. I tried to watch a late night political commentary show, which seems to allocate a maximum of four minutes to the program before breaking for five minutes of adverts. One of the guests was ex HP chief Carly Fiorina, who was fascinating to listen to. Here's someone with real world business experience who has something to say about the state of politics and government. Yet, after four minutes, the presenter stopped "for a word from our sponsors" and then - after the ads - started interviewing somebody entirely different! No wonder our kids suffer from Attention Deficit Hyperactivity Disorder.

    Mind you, back home again, there's something tempting about buying some disused railway wagon and getting it dumped in the wood to provide another alternative writing location. Maybe I could equip it with a small stove and a camp bed, like Roger did with his, and move in for a week to write a chapter about some really complex technology that requires absolute concentration. Though, as my culinary capabilities barely stretch beyond Corn Flakes, I'd probably need my wife to establish a food delivery schedule to prevent me starving to death.

Page 1 of 1 (4 items)