Writing ... or Just Practicing?

Random Disconnected Diatribes of a p&p Documentation Engineer

  • Writing ... or Just Practicing?

    It Configures

    • 0 Comments

    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 with any useful guidance on what they were actually there for. I can now reveal that the software in question was the new configuration tool for version 5.0 of Enterprise Library.

    I have to grudgingly admit that the new configuration tools are extremely good. Yes, I was doubtful when I saw early versions, but now they've tidied them up and made them do useful things, I really do like them. Even if they are almost impossible to successfully "screenshot" for documentation purposes due to the vast amount of horizontal screen width they absorb. Maybe we'll be OK when they invent books with pages that scroll sideways (or everyone starts using e-readers).

    The bits that we (the doc and test teams) struggled with are the advanced configuration options that allow you to generate and consume configuration settings other than all in a single Web.config or App.config file. For some time, because it uses pluggable configuration source providers, Enterprise Library has supported configuration from a database (using a separate sample provider) and configuration that honors Group Policy settings. It's also been possible in the past to generate different run time configurations for different deployment environments, which is useful when the requirements for dev, test, and production systems differ.

    However, in the new version you can use shared and inherited configuration settings. The problem was that the features to enable this were called "hierarchical configuration", "redirected sections", and "rules for configuration merge". We all believed that they only made sense to the developer who created them, and were - to say the least - surprised when even he admitted that he was struggling to identify the scenarios for their use. It's no wonder that we doc and test people were breeding whole new migraines every week.

    What we had ended up with in the docs up to this point was accurate documentation of each feature, together with detailed instructions of how to do it and examples of the resulting XML configuration content. But there was no way you could decide which of the multiple options you needed in order to perform some specific and obvious task, and you ended up being sidetracked by details of how they worked - basically because, by simply playing with them, that's all you could figure out.

    And, of course, the usual documentation nightmare occurs in this situation. As each technical reviewer tries to make sense of it, they add a plethora of comments and suggestions, complete with notes about "things you should tell users" and "important points when using the feature". The result is, not unexpectedly, a guidance document that is basically just a series of notes interspersed with code samples as you try to satisfy all of the requests and feedback. By the time you are done, the content generally makes even less sense, and is even more unusable. All because you didn't (or couldn't) identify at the beginning exactly what the user would want to do.

    But finally, after a long and productive teleconference and consultation with our product manager, we nailed down the scenarios for all this. And, when you see them, it all instantly makes sense:

    • Using a Non-default Configuration Store. In this scenario, you want to store your configuration in a file or other type of store, instead of in the application's App.config or Web.config file. You can use a different file that follows the standard .NET configuration format, use the example SQL Configuration Source available from the Enterprise Library Contrib Web site to load configuration information from a database, or create a custom configuration source.

       

    • Sharing the Same Configuration between Multiple Applications. In this scenario, you want to share configuration settings between multiple applications or application layers that run in different locations, such as on different computers. You simply implement the same configuration as described in the previous scenario, locating the configuration file or store in a central location.

       

    • Managing and Enforcing Configuration for Multiple Applications. In this scenario, you not only want to share configuration settings between multiple applications or application layers that run on different computers (as in the previous scenario), but also be able to manage and enforce these configuration settings for this application or its layers on all machines within the same Active Directory domain. You use the configuration tools to generate Group Policy templates and a Manageable Configuration Source to read your configuration information from a local or a shared configuration file.

       

    • Sharing Configuration Sections across Multiple Applications. In this scenario, you have multiple applications or application layers that must use the same shared configuration for some application blocks. You redirect Enterprise Library to use some shared configuration sections, rather than using a complete shared configuration, and local settings for redirected sections are ignored.

       

    • Applying a Common Configuration Structure for Applications. In this scenario you have a number of applications or application layers that use the same configuration structure and you want to inherit that structure but be able to modify or add individual configuration settings by defining them in your local configuration file. You specify a configuration that inherits settings from a parent configuration source in a shared location, and optionally define local settings that override inherited shared settings.

       

    • Managing Configuration in Different Deployment Environments. In this scenario, you want to be able to define different configuration settings for the same application that will be appropriate when it is deployed to different environments, such as a development and a test environment. You use environmental overrides for settings that are different in two or more environments, and the differences are saved as separate delta configuration files that the administrator then merges when the application is deployed in each environment.

    So, tying each feature to a scenario was the missing link. It meant that I could present a list of "What do you want to do?" options, together with an explanatory schematic for each, and then detail the steps for each scenario separately. And, as most of this was already written, the task was not as time consuming as it had seemed at first. It's amazing what a difference it makes writing guidance for software when you understand what it's supposed to do, rather than having to discover what it does and then try and figure out why it does it...

    And if you decide to play with the software yourself, I'd be really happy to hear if you agree that we finally did nail it. You can get it all from here.

  • Writing ... or Just Practicing?

    Firing Up The Imagination

    • 0 Comments

    Ever since we moved into this house some ten years ago, my wife has irregularly reminded me that she hates the rather cheap and nasty, imitation coal effect, fan driven, generates hardly any warmth, gas fire that the builders installed. Besides which, since we put a flat screen TV above it, we can't actually use it anyway. I took out all the unrealistic imitation coals years ago and replaced them with a nice contemporary array of pebbles, but - I have to agree - it's not exactly an attractive focal point. Especially since we're art deco in terms of the rest of the furnishings.

    So, as it's finally got round to time for redecorating, the executive decision is that we'll junk the fire altogether and go for something different. I suggested we just fill in the hole and get a "roaring log fire" screensaver for the Media Center, which drives the TV. Easy. Quick splash of emulsion on the walls and ceiling, new carpet, and I'm done. However, I was persuaded that we should take a trip to one of those fireplace warehouses to have a look at the different kinds of fires that are available these days. And, as it's a topic I don't generally tend to keep abreast of, I have to say I was stunned by some of the new fangled devices.

    It seems that the "in thing" these days is a wall-hung electric fire that is basically just a big sheet of black glass. Except, when you turn it in, there's imitation flames. And not just some half-hearted flicker from an orange light bulb with a spinning disk on top like the old one I remember my Mother had in her lounge. Oh no, now there is a war going on between manufacturers to provide the most realistic imitation fire effects.

    The salesman patiently explained that one we were looking at contained an array of powerful LED lamps that are filtered electronically, and the light passes through a set of randomly pulsating ribbons driven by a computer-controlled fan, bounces off two mirrors, and is focused onto a back projection screen. In conjunction with the random glowing ember effect generated by more electronics, it actually did look, in a strange kind of way, quite realistic.

    That is, until we went to another showroom where they have one that goes all the way in terms of technology. It uses a large LCD display panel (probably a computer monitor) to display a continually cycling video of a real fire. I guess you couldn't expect anything more realistic than that (unless you take the low-tech route of actually having a real fire). And then the sales lady helpfully intervened by picking up the remote control (!), and demonstrating the three different types of imitation fire video it includes: a roaring log fire, a gently glowing log fire, and a coal fire.

    And there's more. Press some other button and you can adjust the display brightness "to match the ambient room lighting" she explained, or adjust the speed of the flames to suit your current state of mind. And then she pressed another button and a gentle blue "mood lighting" started to emanate from the sides making it seem like the fire was floating on the wall. And you can change the color of the mood lighting to amber or white as well. And don't forget the built-in sleep timer, or the "on-screen" thermostat. Yes, as you press the remote control buttons, a series of menus appear in the middle of the flames!

    And then, just as I was wondering if the world had gone completely mad, she said "Oh, and you'll like this", pressed another button, and the fire started playing burning wood crackling noises. And, as you probably guessed by now, you can adjust the volume to suit your "auditory requirements". Wow. It seems like we could throw away the TV altogether, and pleasantly while away our evenings reprogramming the fire instead.

    OK, so I can see that this is one way to get the ambience of a real fire with no more effort than two screws in the wall and putting a plug on the end of the wire. So how do you explain the electric fire that one of the major manufacturers has just released? It's another LCD monitor type, but it has eight built-in videos. There's the expected log and coal fires, plus six "scenic options" that include a mountain stream, countryside views, a forest glade, and other similar videos. No doubt with the appropriate quantity of birds and animals passing through the scene. And, of course, matching sound for each one. Though they don't, somewhat surprisingly, seem to include an aquarium scene. But they do stress in the adverts that it has a multi-format media card slot, so you can play your own videos and photos. I had to keep reminding myself that we were looking at electric fires.

    But here's the thing. We haven't actually used the existing gas fire at all for more than nine years. We live in a modern centrally-heated house, and we don't need extra warmth. So, if we bought one of these fancy new ones, the only thing it would ever do is play videos of an imitation fire - complete with sound that would rapidly become extremely annoying. And for the price they charge for these wonderful new heating appliances, I could buy a cheap DVD player and a large computer monitor, and still have change left to buy a new sofa and chairs.

    In fact, as there is already a big TV on the wall, it seems like a roaring log fire screensaver is the obvious answer. And it only took a whole day trekking round fireplace showrooms to discover that. "Ah, but", said 'er indoors, "wouldn't it be nice to be able to have some extra heat to warm our toes on those cold winter evenings?" OK, so here's an idea. I'll just buy one of those slim-line fan heaters, spray paint it black, and nail it to the wall behind the TV. Job done.

    And maybe, while I've got the paint brushes out, paint a big black rectangle on the wall below the TV so it looks like we actually have got a posh modern fire. I wonder what the executive decision will be on that...

  • Writing ... or Just Practicing?

    On Cloud Ten

    • 0 Comments

    Two thousand and ten is, they say, the year of the Cloud. Yes, I know they've been saying that for a few years, but it really does seem to be a technology that is heading skywards (ouch, sorry) this year. And I'm about to climb on board. Though, hopefully, not equipped with pan pipes or tendering my CV to St. Peter. I've finally managed to dig an escape tunnel and flee the clutches of Enterprise Library 5.0 now we've got the Hands On Labs done, and before they think of anything else I need to write about.

    And just to prove that this is the start of something big, all the global sales teams here at Microsoft were treated to a special presentation and training event about how it changes the whole technology business paradigm (or something marketing-speak like that). Meanwhile, I'm just starting to catch up on the Windows Azure Guidance (WAG) project here at p&p. A project that I should have been working on for the last three months. So I need to do some serious "accelerated learning", as they call it in the trade.

    However, even though I work for p&p in Redmond, I live in England and am employed by Microsoft UK. Which is functionally part of the sales and marketing group (SMG). And, therefore, the exciting Cloud Training event is mandatory for all staff. OK, so usually I just keep my head down when SMG stuff is floating around, but this time they are monitoring take-up (and there is a test at the end) so I did the online version of the training this week. And I'm still recovering. Normally, training for my role involves placid activities such as reading books about software architecture and code languages. But that's not the way they do it in SMG.

    It's odd because I spent 20 years pretending to be a salesman for a variety of different manufacturers and wholesalers, so I should be hardened to this stuff. But it's a good thing I was debugging some sample apps at the same time or I reckon I'd have been chewing lumps out of the edge of the desk. Not only was there a weather report by an unbelievably excitable young lady about "increasing cloud across all areas", but even an American Football match between all of the rival vendors with an excruciatingly over-the-top commentary. Though I guess these were only the light-hearted fillings between the hard sell and marketing penetration stuff.

    Still, I passed the test and got my course credit, so I should be safe for a few months. And I actually did learn quite a bit about the market that Cloud targets, and its relevance from a business point of view. I guess it will be useful as we document the technical scenarios and provide implementation guidance through our WAG project. I just need to be really careful to avoid any obvious (but oh so tempting) puns around the project name. And just when the World Cup is starting...

  • Writing ... or Just Practicing?

    The Soundtrack for Our Lives

    • 0 Comments

    Watching a rock music documentary on TV the other day, I heard one of my favorite presenters, Mark Radcliffe, utter the wonderful phrase "Lead guitarists are people who create the soundtrack for our lives". Maybe you have to be of the right generation (it's probably less relevant if your music tastes are limited to folk music, garage, or grunge) but to me it really, if you'll pardon the pun, struck a chord. It requires only the first few bars of a classic rock track, or a snippet of a well-known and much loved guitar solo, to switch my brain into neutral and instantly block any capability for logical thought. Somewhat worrying when I'm trying to write technical guidance while Media Player is tuned to the random music stream exposed by my file server.

    I suppose it's partly because I spent my formative years in the period that is now associated with classic rock, that so many of the legends and their music are woven into my consciousness. Yes there are bands around today still creating that magical aura, though even the young kids seem to have a passion that's hard to understand for music that is, in many cases, 30 or even 40 years old. It's odd that rock music has that effect. I can't say I know of many young people who have anything like the same passion for swing, jazz, big band; or for the crooners and songstresses that were the "in thing" of my parents' generation. What is it about classic rock that has radio stations all over the world playing it 24 hours a day, bands where the members should long ago have retired still selling out stadium tours, and endless documentaries and concerts on TV?

    And by some odd coincidence, last Sunday I went to see a rock tribute band at a local club - mainly because my wife's cousin plays bass guitar for them. The band, Floydian Slip, perform a range of classic Pink Floyd tracks from Dark Side and The Wall. Unfortunately none of Syd Barrett's earlier work that I remember so well (think "See Emily Play" and "Piper at the Gates of Dawn"). But they are extremely good. The technical accuracy is amazing, and the atmosphere they generate is incredible. Music originally written in 1973, yet some 37 years later is still magical, innovative, relevant, strange, and yet wonderful.

    It's hard to think of anything in our industry that you could say the same about after 7 years, never mind 37 years. OK, so I know there are people who still play Space Invaders and Aliens in DOS mode, and there's bound to be somebody somewhere who can't bear to be parted from Windows 3.1. But even XP and Windows 2000, which are barely 10 years old, now somehow seem dated, old fashioned, and unexciting. How is it that a few assorted sound waves generated by amplifying the noise of some pieces of vibrating wire can still create such emotional and magical effect, compared to the way that the full-featured multi-media capability of computer programs seems passé after only a fraction of that time?

  • Writing ... or Just Practicing?

    And The Winner Is...?

    • 0 Comments

    Oh how we Brits laughed when the people of the US couldn't seem to decide who was going to be their next president! With their hanging chads, threats of legal action, and people standing in queues for four hours to vote - how could all this happen in a modern, technologically advanced, democratic society? And then we decided to have an election here in Britain...

    For a while it seemed like it would be weeks before we found out who actually won, depending on who could be best friends with somebody else. Or until they figured out how many postal votes were rigged. Or what they were going to do about all the thousands of people who couldn't vote because there weren't enough staff in the polling stations. And, yes, it looks like we can still expect some legal action as well. I suppose the only consoling factor is that the whole process only lasted three months rather than a year and a half like it does in the US.

    But there is one major advantage - at least for a few weeks while they sort it all out we will be safe from the onslaught of stupid new laws. I suppose it's also one way of saving money and reducing our debt burden. Maybe we'll discover that we can get along a lot better without actually having a Government at all.

    And, best of all, it turns out that the leader of the party that experienced the second largest fall in its support is the one who decided who will govern us for the next five years - or until they all fall out with each other and stop being best friends so we can have another go at voting.

    I remember, as a kid, reading a Ray Bradbury story about how - in the distant future - elections will be decided by a single person casting one vote. The argument goes that, by then, the whole population will be so closely monitored, analysed, and documented in minute detail on a myriad huge databases that a computer will be able to select the one person who's views exactly mirror the majority of the population. They will be able to just get that chosen person to make the decision. And it seems that, this year, that person is Nick Clegg.

    It's lucky they didn't use the same database as one of the major junk mail companies here in England. They manage to include two misspellings in my name, and three mistakes in my address. Though that doesn't seem to stop the post lady from shoving the constant stream of useless advertising through my letter box. But it would have been interesting to see the outcome when some poor guy called Dirk Clark in Cleckheaton answered the phone, and the Queen asked him who he wanted to be prime minister this time.

    Mind you, I liked the comment in a letter to the newspaper that said "I just heard that we can anticipate a hung parliament. While I can understand that this is what they deserve after the expenses scandal, surely a good smacking would be a better punishment. Hanging seems a rather extreme option..."

Page 1 of 1 (5 items)