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…