Summary

Motley:  Design is done when that 3 day period I have to do design has expired.

Maven: Design is done when your stakeholders are satisfied. Stakeholders include you, your peers, the test team, architect, future maintainers, your manager, and customer support.

______________________________

[Context:  In a continuing conversation about design, Maven asks Motley an important question]

Maven: Mot, so based on all this stuff about design principles and how to judge whether a design is good, how do you know when you are "done" with design?

Motley: Here's the way it works - we create a schedule for development, and I typically have a few days for the design phase. When I use up that time, my design is done. If it happens to be three days, then at the end of that three days, I'm finished - on to coding.

Maven: What if you still have unexplored areas?

Motley: I'll figure it out during coding. We did talk about emergent design, right?

Maven: You're right - some details will emerge as you are coding, but there are some big picture things you need to nail down during your so-called design phase.

Motley: Yeah, and we get three days for that. Are you hearing okay today?

Maven: We need to be more scientific than that. Some tasks should be time-boxed, but design really isn't one of them. Let me start with this question - who are you doing design for?

Motley: Me! I want to think about the problem up front such that I have confidence to get the code written with minimal mistakes.

Maven: Great start! Who else is design for?

Motley: Ummm, myself and I? What are you talking about?!?! I do design for me - no one else.

Maven: Here's where the confusion lies. Your design is not just for you, but other stakeholders in the project. Here are a few:

• Yourself: You mentioned this already - you want to have confidence that you have thought through the high-level details enough to proceed.
• Your peers: How can someone review your ideas if they don't have anything to review? Creating at least a minimal design document (could be photos of a whiteboard) is necessary to help others validate your thinking.
• Test Team: In order for the test team to do their jobs and create automation test suites, they need to know what developers have in mind for the design. Testers want to know how testability hooks will be placed in the design, and, for example, how they will go about performance testing. They have several needs of the design.
• Architects: If your team has an architect, that person will want to validate that your feature fits in with the overall technical vision of the product. An architect will probably want to see a layer diagram, integration details, how errors are handled, and other information.
• Future maintainers: The next person to maintain your code will be much better off with an up-to-date design document to get them started. The high level details that a design provides is a great lead-in to the code.
• Your manager: A technical manager will want to know what you have planned.
• Customer Support Services: CSS will want to know what supportability hooks you are planning so that they can plan their support mechanisms for the product. Some CSS teams will not even accept your product for support without a design document, particularly if they do front-line on-site support.

Motley: I think you've been sniffing glue again. If I do design to satisfy all those stakeholders, my document will end up being 150 pages long and I'll need much more than three days to do design!

Maven: Don't get carried away, my friend. Agile and lean say to do "just enough" and cut down on wasted effort. You want to talk to each of these (groups of) people beforehand to find out exactly what they need from the design. If the answer comes back as "nothing", then don't bother with that piece of the design. Get expectations up front and do your best to satisfy them. Once you have expectations set, you'll know exactly how much to do and nothing more. Plus, you can make a much more reasonable estimate on how long design will take instead of just time-boxing the time.

Motley: So if my peers, for example, just need a class diagram with a bit of explanation of what I am doing, that's all I should do?

Maven: You bet. Do just enough to satisfy everyone's needs.

Motley: I bet I could come up with a nice minimal doc template that guides the developers on the team when doing design. I just need to interview the various groups to find out what they need. I like this lazy approach - do the least amount needed.

Maven: You have some great ideas, Mot. I'd love to see the template when you're done!

______________________________

Maven's Pointer: Combine a nice minimal design doc template with a good checklist that acts as a reminder to check, for example, design principles. And also note that a "doc template" does not necessary imply a MS Word document template. You could just as easily store your design documentation in a more collaborative space like a wiki.

Maven's Resources:  None this time