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...

Comments

• Anonymous
  March 28, 2010
  As a developer I sincerely apologize for all the trouble we (developers) are causing. Maybe it is because most developers hate writing, mostly because they are not good at it. I have to admit that I'm mostly a big fan of sample code and demo material over written documentation. But many times I've been helped by proper documentation and even more times cursed the lack of it. What I recall of the agile way is that documentation can have a respectable place. Just don't pretend you're writing documentation and then virtually abandon it. If the customer wants documentation, it's just part of a delivered product and should be treated like among equals. But I guess having to slap that into the devs faces all the time is a different thing. Still, I say we (developers) should listen to technical writers. If you can't document it, there's good chance it's just too complex for anyone. I remember Unity's predecessor, I never got my brain around that beast. And I really did try. I understand your dilemma of choosing a path between 'agile documentation' and 'proper documentation patterns' but this sounds like the devs should take a step back and listen to you. Heck, I say turn the thing around. Document the key scenarios first and then start writing code. It wouldn't be the first time devs first create a solution before describing the problem. Keep up the blogging and keep up the good work!

• Anonymous
  March 28, 2010
  Thanks Frank. I appreciate your feedback and comments. Especially "Document the key scenarios first and then start writing code." I suspect that this would make life much easier for the writer. On projects I've been involved with where this has happened it certainly seemed not only to make our task easier, but also provided better and more structured documentation. But would it still be agile...?

• Anonymous
  March 28, 2010
  If I remember correctly a (perhaps even the) driving force of agility is customer focus. You don't want to do anything that is not of benefit to the customer. Just enough process and architecture. Even unit tests benefit the user, albeit indirectly. In that light formulating a key scenario before implementing a feature seems almost a no-brainer. And it's not 'waterfall', just 'think before you act'. But I suspect in some cases I fear that agility turns into a 'developer focused' process, especially when there is no customer (representative) as a project member.  I'm not sure what your situtation is with the P&P team but I suspect most customer representatives are on the other site of the internet cloud. And they are also developers, that might make it worse. But correct me if I'm wrong. <rant>A sad example of that, not related to P&P, is the whole dependency injection hype. Suddenly it's okay to stuff your code with plumbing, for the glory of 100% code coverage. Last thing I remember is that we were striving for as little plumbing as possible. Mind you, libraries like Unity alleviate that, but it's still more complex than a simple 'new'. But that's a whole other topic.</rant> I'm not quite an insider but I praise the P&P teams ask for feedback all the time. But I think they still prefer to publish something first. There are good reasons for that I'm sure but maybe the inability to describe a key scenario is a sign (like a code smell) that the product is a 'shot in the dark'. I really, really, really don't want to criticize the way you do your work but if it is really so hard to document something maybe you should just turn it around to the developer and ask him/her what the heck kind of customer scenario they are trying to solve. I know I easily get carried away when coding and need someone to snap me back to reality. Sorry for hijacking this post a bit, I've just stumbled upon it through the master MSDN blog feed. I find it hard to write documentation so the dilemmas you describe resonate with me. As does the docile/unflappable part.

• Anonymous
  March 28, 2010
  One of my responsibilities as part of the documentation team is to act as the customer/user advocate, which I guess is why I agonize so over getting the docs to provide maximum guidance without "getting in the way" of the development process (for the dev team and for the user). Plus, of course, it's my job - p&p are, after all, primarily a provider of guidance for using Microsoft products. And we generally do press the dev team to describe the key scenarios where they are not obvious. What would be worrying is if even they can't describe them...

• Anonymous
  March 28, 2010
  Well to me that sounds as agile as it gets. IMHO ideally an API is self-describing with documentation to back it up and a tutorial or some sample code is enough to get you started. That's what you mean with 'maximum guidance' and 'not getting in the way', right? Unless you're creating some niche API that sounds like a pretty hard requirement. If it's too hard to learn there's a good chance people won't be using it, even if it's the ideal answer for a problem. So, be the advocate I say! ;-) Sounds like a great job to be amongst the smart people at p&p.

• Anonymous
  March 28, 2010
  It certainly is...!