SPECIFICATION
BY EXAMPLE
SPECIFICATION
BY EXAMPLE
How successful teams deliver the right software
Gojko Adzic
MANNING
Shelter Island
For online information and ordering of this and other Manning books, please visit www.manning.com. The publisher offers discounts on this book when ordered in quantity. For more information, please contact:
Special Sales Department Manning Publications Co. 20 Baldwin Road
PO Box 261
Shelter Island, NY 11964 Email: orders@manning.com
©2011 by Manning Publications Co. All rights reserved.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by means electronic, mechanical, photocopying, or otherwise, without prior written permission of the publisher.
Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in the book, and Manning Publications was aware of a trademark claim, the designations have been printed in initial caps or all caps.
Recognizing also our responsibility to conserve the resources of our planet, Manning books are printed on paper that is at least 15 percent recycled and processed without the use of elemental chlorine
Manning Publications Co. |
Development Editor: Jeff Bleiel |
20 Baldwin Road |
Copyeditors: June Eding, Linda Recktenwald |
PO Box 261 |
Illustrator: Martin Murtonen |
Shelter Island, NY 11964 |
Designer: Leslie Haimes |
ISBN 9781617290084
Printed in the United States of America
1 2 3 4 5 6 7 8 9 10 – MAL – 16 15 14 13 12 11
Contents
Contents v Preface xiii
Acknowledgments xxii About the author xxiii
About the cover illustration xxiv
PART 1 Getting Started 1 Key beneits 3
2
3
Implementing changes more eficiently.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Higher product quality. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Less rework.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Better work alignment .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Remember.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Key process patterns 17
Deriving scope from goals.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Specifying collaboratively.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Illustrating using examples.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Reining the speciication.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Automating validation without changing speciications .. . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Validating frequently.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Evolving a documentation system .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 A practical example.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Business goal.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 An.example.of.a.good.business.goal.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Scope .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 User.stories.for.a.basic.loyalty.system. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Key examples.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Key.Examples:.Free.delivery..................................................................................................... |
26 |
Speciication with examples .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Free.delivery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Examples.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Executable speciication.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Living documentation.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Remember.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Living documentation 29
Why we need authoritative documentation .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Tests can be good documentation .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Creating documentation from executable speciications. . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Beneits of the documentation-centric model .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Remember.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
4Initiating the changes 36
How to begin changing the process.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Implement.Speciication.by.Example.as.part.of.a.wider.process.change
. When:.On.greenield.projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38 Focus.on.improving.quality.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Start.with.functional.test.automation
. When:.Appying.to.an.existing.project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39 Introduce.a.tool.for.executable.speciications
. When:.Testers.own.test.automation.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41 Use.test-driven.development.as.a.stepping.stone
. When:.Developers.have.a.good.understanding.of.TDD .. . . . . . . . . . . . . . . . . . . . . . . . . . . 42
How to begin changing the team culture................................................................................ |
43 |
Avoid.“agile”.terminology
. When:.Working.in.an.environment.that’s.resistant.to.change .. . . . . . . . . . . . . . . . . . . . . . 43
Ensure.you.have.management.support.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Sell.Speciication.by.Example.as.a.better.way.to.do.acceptance.testing .. . . . . . . . . . . . . . . . . 45
Don’t.make.test.automation.the.end.goal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Don’t.focus.on.a.tool.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Keep.one.person.on.legacy.scripts.during.migration
. When:.Introducing.functional.automation.to.legacy.systems. . . . . . . . . . . . . . . . . . . . . . . 48
Track.who.is.running—and.not.running—automated.checks
. When:.Developers.are.reluctant.to.participate.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
How teams integrated collaboration into lows and iterations. . . . . . . . . . . . . . . . . . . . . . |
49 |
|
Global talent management team at ultimate software................................................... |
51 |
|
Sierra team at BNP paribas.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . |
52 |
|
Sky Network services .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . |
53 |
|
Dealing with sign-off and traceability.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . |
55 |
|
Keep.executable.speciications.in.a.version.control.system.. . . . . . . . . . . . . . . . . . . . . . . . . . . |
56 |
|
Get.sign-off.on.exported.living.documentation |
|
|
. |
When:.Signing.off.iteration.by.iteration.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 |
|
Get.sign-off.on.scope,.not.speciications |
|
|
. |
When:.Signing.off.longer.milestones.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57 |
|
Get.sign-off.on.“slimmed.down.use.cases” |
|
|
. |
When:.Regulatory.sign-off.requires.details.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 |
|
Introduce.use.case.realizations |
|
|
. |
When:.All.details.are.required.for.sign-off.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 |
|
Warning signs.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Watch out for tests that change frequently.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Watch out for boomerangs.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Watch out for organizational misalignment.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Watch out for just-in-case code .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Watch out for shotgun surgery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Remember.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
5
6
PART 2 Key process patterns
Deriving scope from goals 65
Building the right scope.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Understand.the.“why”.and.“who” .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Understand.where.the.value.is.coming.from.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Understand.what.outputs.the.business.users.expect.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Have.developers.provide.the.“I.want”.part.of.user.stories
. When:.Business.users.trust.the.development.team.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71
Collaborating on scope without high-level control.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Ask.how.something.would.be.useful.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Ask.for.an.alternative.solution.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Don’t.look.only.at.the.lowest.level.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Make.sure.teams.deliver.complete.features
. When:.Large.multisite.projects.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Further information.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Remember.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Specifying collaboratively 77
Why do we need to collaborate on speciications?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
The most popular collaborative models.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Try.big,.all-team.workshops
. When:.Starting.out.with.speciication.by.example.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Try.smaller.workshops.(“Three.Amigos”)
. When:.Domain.requires.frequent.clariication.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Pair-writing
. When:.Mature.products.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83 Have.developers.frequently.review.tests.before.an.iteration
. When:.Analysts.writing.tests.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Try.informal.conversations
. When:.Business.stakeholders.are.readily.available .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Preparing for collaboration .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Hold.introductory.meetings
. When:.Project.has.many.stakeholders.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87 Involve.stakeholders .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Undertake.detailed.preparation.and.review.up.front
. When:.Remote.Stakeholders.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Have.team.members.review.stories.early
. When:.Analysts/domain.experts.are.a.bottleneck. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Prepare.only.initial.examples
. When:.Stakeholders.are.readily.available.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91 Don’t.hinder.discussion.by.overpreparing. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Choosing a collaboration model.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Remember.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
vii
7
8
Illustrating using examples 95
Illustrating using examples: an example.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Examples should be precise .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Don’t.have.yes/no.answers.in.your.examples
. When:.The.underlying.concept.isn’t.separately.deined.. . . . . . . . . . . . . . . . . . . . . . . . . . .99 Avoid.using.abstract.classes.of.equivalence
. When:.You.can.specify.a.concrete.example.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100 Examples should be complete. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Experiment.with.data.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Ask.for.an.alternative.way.to.check.the.functionality
. When:.Complex/legacy.infrastructures.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Examples should be realistic. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Avoid.making.up.your.own.data
. When:.Data-driven.projects.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Get.basic.examples.directly.from.customers
. When:.Working.with.enterprise.customers.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Examples should be easy to understand.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 Avoid.the.temptation.to.explore.every.combinatorial.possibility .. . . . . . . . . . . . . . . . . . . . . . 105 Look.for.implied.concepts.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Illustrating nonfunctional requirements.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Get.precise.performance.requirements
. When:.Performance.is.a.key.feature.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 Use.low-i.prototypes.for.UI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 Try.the.QUPER.model
. When:.Sliding.scale.requirements.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 Use.a.checklist.for.discussions
. When:.Cross-cutting.concerns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111 Build.a.reference.example
. When:.Requirements.are.impossible.to.quantify.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 Remember.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Reining the speciication 114
An example of a good speciication.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 Free delivery.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 Examples.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 An example of a bad speciication.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
What to focus on when reining speciications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Examples should be precise and testable .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Scripts are not speciications .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Don’t.create.low-like.descriptions.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Speciications should be about business functionality, not software design.. . . . . 121 Avoid.writing.speciications.that.are.tightly.coupled.with.code .. . . . . . . . . . . . . . . . . . . . . . . 121 Resist.the.temptation.to.work.around.technical.dificulties.in.speciications
. When:.Working.on.a.legacy.system.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122 Don’t.get.trapped.in.user.interface.details
. When:.Web.projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124
viii
Speciications should be self-explanatory.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 Use.a.descriptive.title.and.explain.the.goal.using.a.short.paragraph.. . . . . . . . . . . . . . . . . . . 125 Show.and.keep.quiet
. When:.Someone.is.working.on.speciications.alone
. In.order.to:.Check.whether.a.speciication.is.self-explanatory.. . . . . . . . . . . . . . . . . . . . . 125 Don’t.overspecify.examples.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Start.with.basic.examples;.then.expand.through.exploring
. When:.Describing.rules.with.many.parameter.combinations.. . . . . . . . . . . . . . . . . . . . . . 128 Use.“Given-When-Then”.language.in.speciications
. In.order.to:.Make.the.test.easier.to.understand.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 Don’t.explicitly.set.up.all.the.dependencies.in.the.speciication
. When:.Dealing.with.complex.dependencies/referential.integrity .. . . . . . . . . . . . . . . . . . . 130 Apply.defaults.in.the.automation.layer.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 Don’t.always.rely.on.defaults
. When:.Working.with.objects.with.many.attributes.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Speciications should be in domain language . . . . . . . . . . . . . . . . . . . . . . . . 132 Reining in practice.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 Remember.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
9Automating validation without changing speciications 136
Is automation required at all?.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 Starting with automation .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
To.learn.about.tools,.try.a.simple.project.irst
. When:.Working.on.a.legacy.system.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139 Plan.for.automation.upfront. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 Don’t.postpone.or.delegate.automation.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 Avoid.automating.existing.manual.test.scripts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 Gain.trust.with.user.interface.tests
. When:.Team.members.are.skeptical.about.executable.speciications .. . . . . . . . . . . . . . . 143 Managing the automation layer .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Don’t.treat.automation.code.as.second-grade.code.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 Describe.validation.processes.in.the.automation.layer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 Don’t.replicate.business.logic.in.the.test.automation.layer .. . . . . . . . . . . . . . . . . . . . . . . . . . 147 Automate.along.system.boundaries
. When:.Complex.integrations.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 Don’t.check.business.logic.through.the.user.interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 Automate.below.the.skin.of.the.application
. When:.Checking.session.and.worklow.constraints.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 Automating user interfaces .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 Specify.user.interface.functionality.at.a.higher.level.of.abstraction.. . . . . . . . . . . . . . . . . . . . 153
Check.only.UI.functionality.with.UI.speciications
. When:.User.interface.contains.complex.logic.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 Avoid.recorded.UI.tests.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 Set.up.context.in.a.database .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 Test data management.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Avoid.using.prepopulated.data
. When:.Specifying.logic.that’s.not.data.driven.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
ix
10
x
Try.using.prepopulated.reference.data
. When:.Data-driven.systems.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158
Pull.prototypes.from.the.database
. When:.Legacy.data-driven.systems.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160
Remember.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Validating frequently 162
Reducing unreliability.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 Find.the.most.annoying.thing,.ix.it,.and.repeat
. When:.Working.on.a.system.with.bad.automated.test.support.. . . . . . . . . . . . . . . . . . . . 164 Identify.unstable.tests.using.CI.test.history
. When:.Retroitting.automated.testing.into.a.legacy.system.. . . . . . . . . . . . . . . . . . . . . . . 165 Set.up.a.dedicated.continuous.validation.environment .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 Employ.fully.automated.deployment .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 Create.simpler.test.doubles.for.external.systems
. When:.Working.with.external.reference.data.sources .. . . . . . . . . . . . . . . . . . . . . . . . . . . 167 Selectively.isolate.external.systems
. When:.External.systems.participate.in.work. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168 Try.multistage.validation
. When:.Large/multisite.groups.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 Execute.tests.in.transactions
. When:.Executable.speciications.modify.reference.data. . . . . . . . . . . . . . . . . . . . . . . . . . 169 Run.quick.checks.for.reference.data
. When:.Data-driven.systems.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .170 Wait.for.events,.not.for.elapsed.time.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 Make.asynchronous.processing.optional
. When:.Greenield.projects.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 Don’t.use.executable.speciications.as.end-to-end.validations
. When:.Brownield.projects.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172 Getting feedback faster.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Introduce.business.time
. When:.Working.with.temporal.constraints.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173 Break.long.test.packs.into.smaller.modules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 Avoid.using.in-memory.databases.for.testing
. When:.Data-driven.systems.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .174 Separate.quick.and.slow.tests
. When:.A.small.number.of.tests.take.most.of.the.time.to.execute .. . . . . . . . . . . . . . . . . . 175 Keep.overnight.packs.stable
. When:.Slow.tests.run.only.overnight.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176 Create.a.current.iteration.pack.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 Parallelize.test.runs
. When:.You.can.get.more.than.one.test.environment.. . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 Try.disabling.less.risky.tests
. When:.Test.feedback.is.very.slow.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Managing failing tests............................................................................................................... |
179 |
Create.a.known.regression.failures.pack.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Automatically.check.which.tests.are.turned.off
. When:.Failing.tests.are.disabled,.not.moved.to.a.separate.pack .. . . . . . . . . . . . . . . . . . . 181
Remember.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
11 Evolving a documentation system 183
Living documentation should be easy to understand. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 Don’t.create.long.speciications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 Don’t.use.many.small.speciications.to.describe.a.single.feature .. . . . . . . . . . . . . . . . . . . . . 184 Look.for.higher-level.concepts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 Avoid.using.technical.automation.concepts.in.tests
. When:.Stakeholders.aren’t.technical.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 Living documentation should be consistent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 Evolve.a.language .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Base.the.speciication.language.on.personas
. When:.Web.projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .188 Collaborate.on.deining.the.language
. When:.Choosing.not.to.run.speciication.workshops. . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 Document.your.building.blocks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Living documentation should be organized for easy access .. . . . . . . . . . . . . . . . . . . . . . 191 Organize.current.work.by.stories. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 Reorganize.stories.by.functional.areas. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 Organize.along.UI.navigation.routes
. When:.Documenting.user.interfaces.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 Organize.along.business.processes
. When:.End-to-end.use.case.traceability.required. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 Use.tags.instead.of.URLs.when.referring.to.executable.speciications
. When:.You.need.traceability.of.speciications.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Listen to your living documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 Remember. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
12
13
14
PART 3 Case studies uSwitch 201
Starting to change the process.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 Optimizing the process.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 The current process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 The result. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 Key lessons.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
RainStor 211
Changing the process .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 The current process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 Key lessons.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Iowa Student Loan 217
Changing the process .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 Optimizing the process.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Living documentation as competitive advantage.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Key lessons.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
xi
15
16
17
18
Sabre Airline Solutions 224
Changing the process .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 Improving collaboration.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 The result.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 Key lessons.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
ePlan Services 230
Changing the process .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 Living documentation.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 Current process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 Key lessons.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Songkick 237
Changing the process .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238 Current process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 Key lessons.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Concluding thoughts 245
Collaboration on requirements builds trust between stakeholders
and delivery team members .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 Collaboration requires preparation .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 There are many different ways to collaborate.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
Looking at the end goal as business process documentation is a useful model.. . . . . 247 Long-term value comes from living documentation.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
Appendix A Resources 250
Index 255
xii