Random Disconnected Diatribes of a p&p Documentation Engineer
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..."
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:
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.
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...
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, based on requirements. Perhaps it's a bit like an agile development approach to software development. And, by some fortuitous coincidence, we're having a general election here in Britain in a couple of weeks time!
Could it be that software development, especially when undertaken as an agile process, is somewhat akin to the process of Government? When you need to get approval for the project, you can promise almost anything; although ensuring that it bears an uncanny resemblance to the perceived needs of the company and the customers will obviously improve your chance of winning approval. Especially if you can locate some highly selective statistics that prove the need.
Let's face it; this is what prospective candidates and political parties do. We no longer seem to have parties built around a central tenet or a specific vision for society and the country. You often hear people say that the dinosaur statesmen with a firm belief in making the world a better place and working tirelessly for the people have been replaced by career politicians whose main aim is get elected, stay in power as long as possible, and feather their nest to a sufficient extent that occasional after-dinner speeches and personal appearances will keep them in the luxury for their remaining years.
So, step one is to establish focus groups and engage advisors who can tell you what your political beliefs or software design specialties are this week. Step two is to ensure you never exhibit any strong opinions or technical proclivities that may not be in accord with whatever the perceived public opinion or online fad will be next week. Step three is to conceal all deep-rooted beliefs or development shortcomings that may impact your chance of success. Step four is to major on policies or vertical market segments that will generally make no difference at all to the majority of people, or are so vague that they can morph - rather like an agile software development process - to match the ethereal and ever-changing aspirations of the electorate or customer at any point in time.
Of course, there are exceptions to these rules, and we have seen politicians and software houses, both recently and in the not-so-distant past, that offer their own firm vision for the future - irrespective of the headlines in the day's newspapers. Though evidence in the last few years indicates that these usually don't last long. A couple of contentious statements that reveal their innermost belief, political leaning, technical capabilities, or actual level of market penetration are usually enough to have them unceremoniously ejected.
So, working from the premise that you can promise anything at the start, when you need to get the "Go" or when you are trying to garner sufficient votes to become the next incumbent Government, what about some examples of well-designed promises that sound specific and attractive, yet have sufficient wiggle-room that an almost diametrically opposite outcome will still fulfill them:
Pre-election: "We definitely won't raise taxes"Post election: "National Insurance Levy technically isn't a tax"Pre-Go approval: "We will provide the ultimate in user guidance for our product"Post release: "It's so intuitive that, technically, you don't need documentation"
Pre-election: "We will implement small Government"Post election: "You need a huge number of staff to achieve a major reform like that"Pre-Go approval: "It will comfortably handle hundreds of users"Post release: "Yes, but not all at the same time"
Pre-election: "We will implement open Government"Post election: "Except for the things that we need to keep secret"Pre-Go approval: "We will implement an open and extensible framework"Post release: "That only works with our own patented extension technology"
Pre-election: "We will dramatically and aggressively reduce the national debt."Post election: "Over the next twenty five years"Pre-Go approval: "We will dramatically and aggressively reduce the release bug count"Post release: "In the next version"
Pre-election: "We will implement fast broadband Internet connections for all"Post election: "Obviously this does not include the 15% who live in the countryside"Pre-Go approval: "We will implement robust algorithms to ensure the consistency of your data"Post release: "The good news is that only 15% of your data is corrupted"
Pre-election: "We will focus on improving health care for all"Post election: "Obviously this doesn't apply to people who are already ill"Pre-Go approval: "We will focus on improving the performance of our application"Post release: "Obviously this doesn't apply if you have less that 32GB of RAM"
Pre-this post: "I will take the time to make this the best post I've ever written"Post this post: "There was good stuff on TV"
I'm glad I'm not a doctor or a dentist. They say that, if you are, every conversation you have with people who know you starts with a description of the pains in their feet, or asking for advice on which tooth-whitening product is the best. It's bad enough with the business I'm in - once people find out I work for Microsoft I can pretty much predict how long it will be before the conversation comes round to a moan about Windows crashing, advice on getting rid of a virus, help fixing their CD-ROM drive, or a discussion on how they get their favourite photos back after their hard drive died.
But worst of all - the ones I really dread - are the broadband questions. "Which is the best broadband supplier (that charges the least per month)". Or ... "Fred next door says he gets twice the speed from his connection after he installed a program called xxxxx". And, of course, "Why does my connection keep dropping just as I get to the page where I click Place Order and I have to go back and do it all again?"
In fact, I had just this conversation the other week with a friend who seems to think I can remotely diagnose the problem while we are all sitting in a restaurant eating dinner. Mind you, I suspect it might be something to do with the fact that his semi-detached neighbour also has a wireless router from the same company and, as the telephone sockets in the two houses are located in the same place next to the stairs and only separated by a party wall, it's just possible that they might be interfering with each other. Besides that, everyone and their dog seem to have wireless broadband routers in their street, and insist on running them on full power, so it's amazing that anyone can actually connect at all. I did think about suggesting he did a deal with his neighbour and they shared the connection. But that probably violates some condition of the agreement with the phone company.
Mind you, he called me today to tell me that he has changed his broadband supplier, and everything is working wonderfully now. And they only charge nine pounds a month compared to the previous supplier who was charging fifteen. And, best of all, the new supplier actually gave him four months free because he had to pay the remainder of the rental for the contract term with his old supplier to be able to switch. That works out at six pounds a month average for the year. How on earth can his new supplier make any money out of that? Is it so hard to get business now that companies have to almost give stuff away? I wonder what kind of technical support he's likely to get. And then, amazingly, the original supplier actually came back to him with an offer to reduce their price to stay with them!
Here in England, we keep getting promised high speed broadband (which they define as "at least 2MB") available to everyone so that the Government can close down all their offices and call centres, and just communicate with the great unwashed online. They even considered adding a tax onto fixed phone lines to pay for it. So it was interesting to read last week about a guy who was quoted 57,000 pounds to have broadband installed in his remote cottage. Mind you, the phone company did point out that they were being extremely generous in that they would pay the first 8,000 pounds, and just charge him the remainder.
Meanwhile, almost everyone I know also moans about the speed of their connection. They paid for "up to 8MB broadband", yet the Web pages and emails trickle in at one and a bit meg on a good day. I suppose its enlightening to see that the Advertising Standards Authority are trying to make broadband suppliers tell the truth in their ads, but it seems like they (the ASA) might as well be banging their head against the wall. Though they did recently win a case against the company who were advertising their 512KB service as "full speed broadband". And, as the FCC define broadband as being an "always on" service, I wonder if I can claim for the seventeen hours that my service was not "on" due to a major failure at the local exchange?
It pains me to compare the cheap deals with the amount I pay each month for a dual failover connection via ADSL and cable - though it would be rather difficult to actually do my job without connectivity. Any maybe I'm just a born pessimist, but I can't help thinking that you only get what you pay for in this life. My experience with cheap computers has proved this time after time. I've discovered that buying well-known brands means I generally end up getting rid of machines to a worthy cause that are still working simply because they are too old to run the latest software or support the peripherals I need for my work - and not because they've given up the ghost and need a new motherboard, hard drive, or power supply.
Yet almost every time I get asked for advice about buying a new machine, the advicee listens politely and then gleefully phones me a week later to say they bought a wonderful new computer from the local supermarket or some back street dealer at half the price. And then, a few months later, phone again to ask me why the light doesn't some on when they press the button, or if I know what the message "Cannot find NTLDR" means...
There's an ongoing discussion about how we, as a society, should be archiving our heritage to make it available to future generations; that is, if global warming, financial crises, and energy shortages don't finish us off before then. I suppose, for most people, the main focus for domestic memory archiving is all about video, still photos, and music. One of the topics that regularly surfaces is whether a digital format is better, or the old-fashioned "hard copy" approach.
The argument seems to centre on whether we'll actually be able to access the archived data once the storage or encoding format is replaced by newer technologies. Will we still be able to read CD-ROMs when even Blu-Ray becomes a legacy format? Will data on a USB drive still be readable in 50 years time? Will there be viewers or converters for JPEG, MPEG, WMV, and WMA? Or should everything be stored in RAW format?
In one respect, I can maintain the integrity of the digital files simply through the fact that the entire folder trees of our videos, photos, and music on my servers are regularly backed up, and moved as I upgrade machines. So I always have reasonably fresh copies on several disks and CD-ROMs. And I assume, based on the fact that you can still get conversion programs for very old picture formats, I'll be able to convert at least the photos to any new formats that come along.
However, I recently got drawn into the quandary of how to actually preserve old materials rather by chance. It started from conversations with two of my colleagues. One is an avid aircraft fan, and the other a railways enthusiast. As I fit quite neatly into both categories, I thought I'd collect together some of my better old photos from both worlds and pass them across for perusal. Of course, the actual prints are now well dog-eared or lost, but I discovered that my Epson flatbed scanner has a film attachment - and so I set to scanning the original negatives with the idea that this would produce first-class reproductions of the originals and allow me to preserve them for the future. And also view them more easily any time we like on our Media Center with just a few wafts of the remote control.
So it was with horror that I discovered both the degraded state of the original negatives and slides, and the lack of quality from the old cameras that I used over the years to take the photos. Even a borrowed semi-professional film scanner (the PlusTek 7600i) struggled to produce anything even remotely close to the quality of a cheap modern digital camera. Weird color shifts, graininess, scratches, ingrained dust, and general fading resulted in something that my more resembles the results from my rather aging 1 megapixel camera phone.
Each photo requires considerable tuning with an image editor to get something even remotely acceptable. But at least I discovered a good use for the Paint Shop Pro Photo program I was grumbling about in a previous blog post. It's amazing what the digital noise reduction filter, color balance adjustment, sharpness, and other effects can produce from an only half-recognizable image.
Of course, it takes ages to scan, sort, and edit the packets of negatives that go back over a considerable number of years. Thankfully, I'd labeled each set with the location and date, and it is wonderful to see them again after so many years. Definitely a good excuse for an evening reminiscing, wondering where that youthful figure and lack of gray hair went, and marvelling at the interesting sense of fashion we seemed to have in those days. And how we managed to cope with trans-Atlantic travel to conferences and meetings in Redmond, Florida (twice), Palm Springs, and Las Vegas all in in one year. Maybe that's the problem - I'm still suffering from jet-lag.
So far, I'm only around half-way through the stack of negatives, and itching to get started on the boxes of slides. Though I've managed to restore some amazing aircraft photos that go way back to 1986 and 1987 - especially some of the NATO Tactical Fighter Meet held at RAF Waddington, and the air show there the following year. So at least I have something to keep one of my colleagues happy for an hour or so. Here's some samples:
I'll post some for railway enthusiasts in a few weeks time, after I investigate the large box full of slides...
Life was a lot more positive when my grandfather was alive. If he felt ill, he simply had to pop into the local pharmacy, explain his symptoms, and they would sell him a bottle of liquid or a box of pills that were guaranteed to cure him. No prevarication or hint of doubt. The bottle or box would say that "Mr. Smith's Patent Stomach Medicine is guaranteed to cure wind, bloat, queasiness, cramps, and sickness". It probably even cured baldness if you rubbed it on your head, and was also useful for removing boy scouts from horse's hooves.
Compare that to today. I bought a raincoat a while ago, but the label inside studiously avoids saying that it is waterproof. The material is only "water resistant". So if I end up wetter than a white water rafter next time we get a few faint spots of rain, I can't blame them. Likewise, my wrist watch is not longer "shockproof", just "designed to minimize damage from accidental contact with other objects". I wonder if bulletproof vests are now advertised as being "useful in minimizing critical injury from fast-moving projectiles". And, of course, my anti-virus software will only "help to protect me against malware". Like it will just pop up little windows full of soothing phrases the next time I get hit by some virus attack. How long do you reckon it will be before the File menu in my word processor program contains "Attempt to Save (with no guarantee of success in case of write protected files or disk errors)".
And, of course, everything now has to carry more warnings and explanations than it does positive encouragement. Unlike Mr. Smith's medicine, whose packaging happily omitted to mention the fact that it contained arsenic and might make you go blind, almost anything you buy these days seems to be adorned with reams of warnings and get-out clauses almost to the extent of putting you off actually using the product at all. All due, no doubt, to our society's constant drive for "Elf and Safety".
A typical example is when you see a TV advert for a new car. Some impossibly handsome young man drives through country lanes at 90 miles per hour, magically reappears in an Amazonian rain forest, does a couple of turns around the Sahara, and then is seen screeching to a halt inches from the end of the landing deck of an aircraft carrier. Meanwhile, the caption on the screen says "Professional driver on closed circuit - do not attempt"... just in case you decide to go out and buy one, and try this yourself. But imagine what it would be like if the motor car had only been invented last week, and they were now trying to sell it. The advert would go something like:
Now available, a wonderful new way to travel! Faster than any horse and cart, smoother than any stagecoach! More relaxing than any armchair! Now you can go wherever you want, whenever you want, and arrive in style!
Then, below the glorious full color picture, would be the small print:
Note: Driving at speed incurs considerable risk. May not always be faster than a horse and cart, depending on local surface conditions. Ride may be less comfortable than advertised. Does not imply that you will find the experience relaxing. Driving may be a considerable source of stress, resulting in a heart attack, mental disorder, and premature death. Does not imply that all routes are available for travel or that all destinations are available. There may be limitations on the time of travel depending on weather and road conditions. May frighten livestock. Requires considerable maintenance and will regularly require expensive spare parts. Cost may impact your credit rating. Ask your doctor if driving is right for you.
I don't know about you, but staying with a horse and cart sounds like a lot better idea to me. And just think what the list of warnings would look like if you had just invented the PC...
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.
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...