Producing new functional requirements for each project is evil and should be illegal, and punishable by death or working as a tester [1]. It is a basic cause of incoherent system, lack of holistic system thinking, and a lack of coherent documentation to support testing.
We've all had the experience of trying to understand the behaviour of a system and wading through reams of the original specification, change requests, and series of follow-on project specs, so why do we willing perpetrate this mess?
Probably a few main reasons:
1) The model of monolithic documents being prepared, signed-off, and developed against encourage this beahviour.
2) In the short-term it's the fastest way to get your individual project over the line
3) It's how we've been taught to do it
4) When we do decide to do something about it, we don't get angry that we're documenting badly, we get angry that we're documenting _at all_, and we implement some messy mix of agile and waterfall.
5) Wanting to have "all the information in one place" for decision makers (Which is a really valid point)
So what can be done about it? I'd generally propose a few changes that don't involve a massive change to current practices.
1) For new projects try to split out the project ephemera from the functional design that will be re-used.
2) Instead of having a singel plave for all project documentation, have a seperate place for storing project documetnation, system documentation, and process documentation. This reinforces that they should be treated seperately.
3) Gently ease into some business architechture questions, because if you're not using projects as the basic unit of information, you're going to need soemthing to replace it, and a system centric-organisation is a pretty poor substitiute.
4) Get some soom document/knowledge management systems. Shared directories will not work if you're moving towards lots of smaller documents. Consider Sharepoint as your first stop, and moving towards a Wiki and a Modelling tool in the long tem.
All of these mitigate against most of the objections I raised earlier, but they still don't give you the "single view" of the changes you're making for the project. Unfortunately there's no magic-bullet here. The more solution centric you make your documents, the less project centric they become.
Ideally you could mix-and-match content together into dynamic documents. But there's just no good tools for that, confluence is closest but really isn't there yet. There's a good summary of why up at http://confluence.atlassian.com/display/DISC/Using+Confluence+for+professional+documentation.
[1] Nothing against testers. It's just that most BAs hate working as testers.
Tuesday, January 18, 2011
Wednesday, December 22, 2010
Business vs Functional Requirements: I don't care.
Either I’m getting very lazy or I’ve reached a new point of sophistication in my BA practice because I really don’t care that much about the difference between business and functional requirements anymore. Maybe I’m just sick of the fact that it’s almost a point of pride for people to have their own definition.
Not to mention that fact that half of the time the “business” requirements aren’t from the business they’re from customers or regulators, and that “functional requirement” documents include non-functional things like service-levels and look and feel.
Half the time I don't even consciously differentiate between business and functional requirements. I just elicit a bunch of requirements, get the business to sign off to confirm that it looks like we have a shared understanding, and then specify a solution separately.
For me that's the big separation between classes of documents that BA produce
* Elicited Requirements: Documents conversations and consensus with stakeholders, embodies a shared understanding of situation, with the BA's role being mainly a drawing out from stakeholders.
Elicited requirements could be business, functional, stakeholder, objectives, KPIs, NFRs, show tunes, user stories, wire-frames, or just whatever works best for all stakeholders to communicate.
This is a big mess of "business" and "functional" requirements.
* Specified Solution: Documents a single concrete solution that addresses the situation embodied in the elicitation stage, with the BA's role being to design a solution based on the elicited requirements.
In this model I end up collecting mostly "functional" requirements.
I grant this represents my background working as a system integrator. In a fixed-price environment you really want to manage scope by keeping all that vague text in the elicited requirements separate from the model.
This has always worked well for me, with the following provisos:
* Traceability between elicited reqs and the eventual solution is key. You need to show where you took into account all the things your stakeholders said.
* You still need to understand the difference between business and functional requirements on some level so you know where you can implement something differently from the user request (And note it is such in your traceability)
* I’d never talk like this to someone just starting out as a BA. I think when you’re starting out you need to be much pretty dogmatic about the difference between stakeholders expressed needs, and their underlying objectives to avoid becoming an over-paid stenographer.
Not to mention that fact that half of the time the “business” requirements aren’t from the business they’re from customers or regulators, and that “functional requirement” documents include non-functional things like service-levels and look and feel.
Half the time I don't even consciously differentiate between business and functional requirements. I just elicit a bunch of requirements, get the business to sign off to confirm that it looks like we have a shared understanding, and then specify a solution separately.
For me that's the big separation between classes of documents that BA produce
* Elicited Requirements: Documents conversations and consensus with stakeholders, embodies a shared understanding of situation, with the BA's role being mainly a drawing out from stakeholders.
Elicited requirements could be business, functional, stakeholder, objectives, KPIs, NFRs, show tunes, user stories, wire-frames, or just whatever works best for all stakeholders to communicate.
This is a big mess of "business" and "functional" requirements.
* Specified Solution: Documents a single concrete solution that addresses the situation embodied in the elicitation stage, with the BA's role being to design a solution based on the elicited requirements.
In this model I end up collecting mostly "functional" requirements.
I grant this represents my background working as a system integrator. In a fixed-price environment you really want to manage scope by keeping all that vague text in the elicited requirements separate from the model.
This has always worked well for me, with the following provisos:
* Traceability between elicited reqs and the eventual solution is key. You need to show where you took into account all the things your stakeholders said.
* You still need to understand the difference between business and functional requirements on some level so you know where you can implement something differently from the user request (And note it is such in your traceability)
* I’d never talk like this to someone just starting out as a BA. I think when you’re starting out you need to be much pretty dogmatic about the difference between stakeholders expressed needs, and their underlying objectives to avoid becoming an over-paid stenographer.
Thursday, December 9, 2010
Customer Needs, not Functionallity
My Lamy ink pot is so well designed that every time I refill my cheapy $30 fountain pen I get a real sense of satisfaction, because everything just works.
I can feel that they've actually though about:
how a customer will use their product,
the acions they'll take immediatly before and afterwards, and
what place the product has in the customers life.
An inkpot is a fairly simple thing at it's heart. You just need ink in a well sealed container, lamy obvioulsy have great ink, and athe container closes tightly but it's a few little additions that make me willing to pay the %20 price premium over their competitors.
Lamy's have added two main feautres:
An integrated dispenser for plastic backed tissue paper around the base of the ink pot
A little reservoir in the bottom of the pot so that it's easy to get your pen or bladder all the way into the ink, even when you're down to the last of the ink.
So; from a BA point of view what have Lamy done that is so applicable to software design?
Firstly - they didn't think about themselves as providing a function (Ink, Email, holding customer records) instead they saw themselves as supporting an activity (Refilling a pen, communication, communicating with customers). By looking at a wider business-process context they were able to better integrate multiple functional components into something useful to the end user.
From a BA POV they took a wide process, and collapsed distincy activities together by providing a single interface that matches what the customer wanted to acheive. This is putting the customer's needs first, and the functionallity later.
Secondly - they looked at the whole lifecycle of usage. They introduced features that covered the whole product lifecycle, giving the customer unexpected bonuses towards the end of their product use; which usefully for a retail product is just when they're about to re-order.
But what's really great is that there's a synergy between the two, that little reservoir on the bottom is what paper dispenser clips to. There's also ongoing revenue from selling paper refills.
The only thing it's really missing is a way to easily open it when the ink has dried the list shut, maybe if base coudl be made square'ish you could get a grip more easily?
I can feel that they've actually though about:
An inkpot is a fairly simple thing at it's heart. You just need ink in a well sealed container, lamy obvioulsy have great ink, and athe container closes tightly but it's a few little additions that make me willing to pay the %20 price premium over their competitors.
Lamy's have added two main feautres:
So; from a BA point of view what have Lamy done that is so applicable to software design?
Firstly - they didn't think about themselves as providing a function (Ink, Email, holding customer records) instead they saw themselves as supporting an activity (Refilling a pen, communication, communicating with customers). By looking at a wider business-process context they were able to better integrate multiple functional components into something useful to the end user.
From a BA POV they took a wide process, and collapsed distincy activities together by providing a single interface that matches what the customer wanted to acheive. This is putting the customer's needs first, and the functionallity later.
Secondly - they looked at the whole lifecycle of usage. They introduced features that covered the whole product lifecycle, giving the customer unexpected bonuses towards the end of their product use; which usefully for a retail product is just when they're about to re-order.
But what's really great is that there's a synergy between the two, that little reservoir on the bottom is what paper dispenser clips to. There's also ongoing revenue from selling paper refills.
The only thing it's really missing is a way to easily open it when the ink has dried the list shut, maybe if base coudl be made square'ish you could get a grip more easily?
Sunday, November 28, 2010
Requirements as risk mitigation
Really detailed use cases, and complete entity-relationship get a bad rap because they can be very complex to read, and are often not particularly good at describing the solution to end-users[1].
As a result they can get called a waste of time. We assume that requirements must be easily understood by business and IT stakeholders, and they seem to fail this rule - but most people persist with them out of a sort of gut-feel that they're useful despite being confusing to most users; and they're right to.
These sort of requirements mitigates your risk of internal incoherence, unwritten assumptions, and unexplored options. They may not be immediately readable by end-users but they ensure that the author has done a structured analysis of all the possibilities.
For example I had a project go wrong once because we assumed that each purchase order resulted in a single invoice, (e.g. a 1 to 1 relationship) when the reality was more complex (many to many). If a detailed ER diagram had been constructed the author would have raised this as explicit assumption. Similarly detailed use cases with very formal treatment of alternate paths are great at driving out odd little edge conditions.
Sometimes we produce requirements not to describe it to others, but to make sure we're across all the detail ourselves. This isn't the sort of work that gets users excited, but it does guard against something going wrong down the track.
[1] I've got some other posts about how to mitigate this, but that's another discussion
As a result they can get called a waste of time. We assume that requirements must be easily understood by business and IT stakeholders, and they seem to fail this rule - but most people persist with them out of a sort of gut-feel that they're useful despite being confusing to most users; and they're right to.
These sort of requirements mitigates your risk of internal incoherence, unwritten assumptions, and unexplored options. They may not be immediately readable by end-users but they ensure that the author has done a structured analysis of all the possibilities.
For example I had a project go wrong once because we assumed that each purchase order resulted in a single invoice, (e.g. a 1 to 1 relationship) when the reality was more complex (many to many). If a detailed ER diagram had been constructed the author would have raised this as explicit assumption. Similarly detailed use cases with very formal treatment of alternate paths are great at driving out odd little edge conditions.
Sometimes we produce requirements not to describe it to others, but to make sure we're across all the detail ourselves. This isn't the sort of work that gets users excited, but it does guard against something going wrong down the track.
[1] I've got some other posts about how to mitigate this, but that's another discussion
Thursday, September 16, 2010
Three Types of Requirements
There are really only three methods for describing requirements in the whole world, these are:
* Imperative: "The system shall....."
* Prescriptive: "X = Y * 5. If X then Y. Use Cases, ER Diagrams, etc".
* Narrative: Bob hits X, Y happens, then Z. This is because A is true. If B were true we would do this.
Imperative is how everyone starts of doing requirements in their first job. Those long lists of "requirements" that make everyone's lives so miserable. IMHO you should never use these for anything but the simplest project.
Prescriptive is the model we move to after we've been hurt by scope creep a few times. We'll just lock everything down in a detailed unambiguous model that is 300 pages of impenetrable UML, and then we'll be OK. We won't have capture what the user actually wants, but at least we'll have documented it unambiguously.
Narrative is where we realise that our systems are only part of larger stories, and need to be seen in that context and we make the customer the centre of our design by giving them the starring role in the story. User Stories, or well-written use cases are good examples here.
This distinction has nothing to do with functional vs. business requirements. It's a seperate dimention about how we document requriements. The type of requirement is a compeltly seperate discussion.
* Imperative: "The system shall....."
* Prescriptive: "X = Y * 5. If X then Y. Use Cases, ER Diagrams, etc".
* Narrative: Bob hits X, Y happens, then Z. This is because A is true. If B were true we would do this.
Imperative is how everyone starts of doing requirements in their first job. Those long lists of "requirements" that make everyone's lives so miserable. IMHO you should never use these for anything but the simplest project.
Prescriptive is the model we move to after we've been hurt by scope creep a few times. We'll just lock everything down in a detailed unambiguous model that is 300 pages of impenetrable UML, and then we'll be OK. We won't have capture what the user actually wants, but at least we'll have documented it unambiguously.
Narrative is where we realise that our systems are only part of larger stories, and need to be seen in that context and we make the customer the centre of our design by giving them the starring role in the story. User Stories, or well-written use cases are good examples here.
This distinction has nothing to do with functional vs. business requirements. It's a seperate dimention about how we document requriements. The type of requirement is a compeltly seperate discussion.
Monday, August 2, 2010
Discreditting by Diagram
When you are putting together a before and after diagram you want them to be as clean, and as similar to each other as possible. This means that the effect of any changes is clear, and unaffected areas are obvious.
Sometimes though you just want to make the diagram as complicated and ugly looking as possible to get a point across or make a sale. You can't make it look like it's just a bad diagram - you have to give the impression that the author has really tried to make it comprehensible it's just that the underlying idea is bad.
The classic use of this is the IT department trying to get money to do a systems consolidation or re-engineering. The architecture team will dutifully come up with the ugliest diagram of spaghetti known to man, that will get presented as proof of how bad things really are.
Turns out politicians know this trick too; as shown below:
This diagram published by the Republicans on the Joint economic Committee “explaining” Obamacare is a classic of the genre. Undoubtedly high-price (and worth it) consultants have been consulted to make this look so complicated.
High res version here
It has all the classic tools to over complicate something:
Mixing Domains: This shows organisation structure, regulation, stakeholders, responsibilities, impact, legislation, and everything else all on the one page. This lets you put hundreds on boxes on the page
Lots of Boxes: Goes without saying - put as much as you can in there. Go crazy.
Complicated Legend: By having so many domains you get to put an overly complex legend on the bottom that shows all the different sorts of things. This requires lots of different shapes and colour coding. Which leads me to:
Colour: Use at least 7 or 8 different colours. This makes it hard to concentrate on text, and as a bonus you can have them all as similar shades so that when you print it in black and white you can’t tell the difference.
Lot of lines: All blank space should have lots of lines running through it. This way you add a lot of visual complexity, but it’s so hard to see what’s connected to what that you don’t add any content.
Acronyms: Put tons of Acronyms in that way no one can understand it without a glossary, and once you put in a glossary that’s another box of dense text to add to the complexity.
Tiny-Text: Throwing in some boxes with minuscule text give the impression that there’s even more complexity going on under the surface.
Miss the point: Put a crucial stakeholder or system in some out of the way corner, and then put something ridiculous in the centre.
Note: For the purposes of this article I don't particularly care about whether Obamacare is overly complicated or not, a good thing or not, it's just an interesting look at how the diagram designed can push messages.
Sometimes though you just want to make the diagram as complicated and ugly looking as possible to get a point across or make a sale. You can't make it look like it's just a bad diagram - you have to give the impression that the author has really tried to make it comprehensible it's just that the underlying idea is bad.
The classic use of this is the IT department trying to get money to do a systems consolidation or re-engineering. The architecture team will dutifully come up with the ugliest diagram of spaghetti known to man, that will get presented as proof of how bad things really are.
Turns out politicians know this trick too; as shown below:
This diagram published by the Republicans on the Joint economic Committee “explaining” Obamacare is a classic of the genre. Undoubtedly high-price (and worth it) consultants have been consulted to make this look so complicated.
High res version here
It has all the classic tools to over complicate something:
Note: For the purposes of this article I don't particularly care about whether Obamacare is overly complicated or not, a good thing or not, it's just an interesting look at how the diagram designed can push messages.
Tuesday, July 27, 2010
We must hate trees a lot..
Why must every document I see start with at least 3 pages that are completely useless? Most of them manage at least 6, and I've seen up to 20.
Sometimes I just want to take these docs, scroll through until I find the first statement someone could reasonably disagree with, and just delete everything before this point. I don’t think anyone would miss it except for some putz who will insist it all the goes back in on the ground that it's "standard".
This useless filler generally consists of:
Title page. Generally containing no more content than is available in the document headers and footers anyway.
Distribution and sign-off page. This never contains any record of actual sign-off, the distribution lists is always out of date. Old emails will always be used to substantiate the real distribution in any case.
Version history. This is either so terse it’s useless, or so involved it takes three pages. It is never used by anyone; again the email trail is used as the de-facto history. Maybe if you document control system supports version that could be used.
Glossary and Abbreviation. A list of items that are either so obvious that all reader’s will understand and know them already, Acronyms so obscure that even spelling them out helps no one, or items explained in-depth inside the document anyway. No one will ever read or use this.
Document Purpose/Audience/etc. A whole bunch of explanation about what the document is meant to do and for whom. Arguably defensible for a “one-off” type of document; but for a standard template that you use again and again does the audience really need reminding that the purpose of a business case is to secure funding? It’s either things readers already know, or if they don’t know it they need more education than you can fit into the document intro.
Project scope/benefits/overview/context/etc. A whole bunch of generic description of the project that’s repeated (in slightly different wording) in every single document. In the best case scenario readers will just skip this; in the worst it will be different between documents causing confusion.
What’s the end result? 40 page documents where content that really matters doesn’t start until page 10. I’ve personally produced mounds of documents that are over %75 filler. This increases the cost of producing documentation, slows down review, and damages document readability. You can see why the whole idea of documenting an IT project is under attack.
What’s really galling is that this document bloat doesn’t come from business customers demanding more – the pressure is from inside the IT. Look at a memo, or a board paper. You’re lucky if there are more than a few centimetres of document meta-information at the top. A paper going to the board to recommend a few million dollars of spend fits on a single A4 sheet; but the smallest IT document we manage to make as long as war and peace, but with as much content as a limerick.
Solutions?
Manage meta-info (versions, approvals, distributions, etc) in the same system that manages your documents. If your system can’t support that and you really think you need it (unlikely) then at least move it into an appendix.
Remove purely aesthetic cover pages, unless you’re writing a book it’s just getting in the way.
Centralise repeated information in a living document. The project scope and overview document should be the only place that summarises repeated general project information. Put all the effort of re-drafting, re-reviewing, and re-writing the same content in every document into keeping it up to date instead. If you really have to reference it at the start of the document, if you really, really have to then copy and paste it with a explicit statement about where it was copied from.
Do what I said at the start of this post. Start at the top of the document, scroll down until you find the first statement someone could reasonably disagree with, and just delete everything before this point.
Sometimes I just want to take these docs, scroll through until I find the first statement someone could reasonably disagree with, and just delete everything before this point. I don’t think anyone would miss it except for some putz who will insist it all the goes back in on the ground that it's "standard".
This useless filler generally consists of:
What’s the end result? 40 page documents where content that really matters doesn’t start until page 10. I’ve personally produced mounds of documents that are over %75 filler. This increases the cost of producing documentation, slows down review, and damages document readability. You can see why the whole idea of documenting an IT project is under attack.
What’s really galling is that this document bloat doesn’t come from business customers demanding more – the pressure is from inside the IT. Look at a memo, or a board paper. You’re lucky if there are more than a few centimetres of document meta-information at the top. A paper going to the board to recommend a few million dollars of spend fits on a single A4 sheet; but the smallest IT document we manage to make as long as war and peace, but with as much content as a limerick.
Solutions?
Subscribe to:
Posts (Atom)
Posts
