[EXAMPLE] Design Process Guide

Also see my Design Document Template. By Joel Thornton.

Overview

Edit Edit

This page outlines a process that can be used to quickly and comprehensively create a design for a new product, feature or service.

By following this process and guidance, we help ensure that our implementations are properly vetted, meet a high quality bar, are well documented, and can be implemented efficiently.

Glossary

Edit Edit
MoSCoW method
An acronym derived from the phrases "Must Have", "Should Have", "Nice to Have", and "Won't Have". The MoSCoW method is used to clarify the priority of each requirement.
Project
The subject of a design and implementation effort, having some set of concrete deliverables as its output.
SMART criteria
An acronym for Specific, Measurable, Achievable, Relevant, Timely. Applying the SMART criteria to design requirements ensures they meet a high bar for correctness, clarity, and attainability.
Stakeholder
Any person or party who has a vested interested in the project. This may include customers, teammates, managers, and partner teams.

Why create a design?

Edit Edit

Up-front design means we solve many classes of problems before writing a single line of code. Once you start coding, it becomes increasingly expensive to change the implementation later. For this reason, we should put effort into solving as much of the problem "on paper" as we can before we begin the real work of implementation. This is the essential benefit of design.

Should I create a design?

Edit Edit

If the answer to any of the following questions is "yes" for a project, you should create a design for it:

  • Do you expect the work to take more than 4 dev-weeks?
  • Does the work have a significant blast radius or risk: how can it impact other teams and customers?
  • Is it ambiguous enough to warrant a discussion of >30 minutes?
  • Do external groups need to know about or participate in the design?
  • Is it worth having the implementation's design documented? (Is the behavior/rationale of the implementation not apparent just from reading the code comments?)

Why create a design document?

Edit Edit

If a project is big enough to justify a design, then it's big enough to warrant a dedicated design document. 

Design documents are "living documents" which give all stakeholders a single document of record that can be referenced for the lifetime of the project/feature. 

Creating design documents helps get broad consensus and buy-in from stakeholders, and helps suss out issues before implementation that would be much more costly to change post-implementation.

Some benefits that are realized by having a good design document:

  • Consensus: buy-in can be obtained from all stakeholders early in the development lifecycle, which promotes a common understanding of what the end product will be
  • Verifiable: the implementation can be verified to adhere to the design and requirements
  • Higher Quality: the implementation will tend to be of higher quality, with better behavior and fewer bugs thanks to thorough and unambiguous requirements which have been reviewed by stakeholders
  • Faster: an implementation backed by a good design document takes less overall time to implement due to clear guidance and the minimization of scope creep/requirements churn
  • Parallelizable: implementations can be readily worked on by the whole team due to the existence of a central shared document of record
  • Documented: the implementation will begin life with a high quality body of documentation that can be relied on and evolved going forward

The design process

Edit Edit

These are the high level steps that should be followed for all designs:

  1. Begin a new design document.
  2. Define the high level objectives.
  3. Conduct an informal principal review.
  4. Determine requirements.
  5. Iterate on the design.
  6. Conduct reviews.
  7. Create an implementation plan.

Each of the above bullet-point steps should be executed for all designs. However, be Agile! Remember the Agile motto: Do the simplest thing that works. Designs don't have to be huge, drawn-out processes with exhaustive documentation. Size the design and documentation appropriately to the project at hand.

Creating a design is an iterative process. For example, you may need to bounce betweeen determining requirements, writing design details, and conducting reviews several times before you settle on a finished design. Don't be afraid to jump around and try different things. 

After each step, seek to obtain sign-off from all relevant stakeholders. Doing so ensures we gather the best feedback at the earliest point in the project's lifecycle (when it is cheapest to incorporate), while also promoting healthy consensus on the design from all stakeholders.

Throughout the process, use your best judgment, and don't hesitate to ask for input from a peer.

Begin a new design document

Edit Edit

Create your initial design document.

This document is the project's specification and document of record: it should be referred to in all cases where there is a question about the project requirements or design. If a person or another document disagrees with this document, then this document should be treated as the single source of truth for the project.

This document is a living document: it is expected to evolve over time to reflect the current consensus understanding of the design. 

Define the high level objectives

Edit Edit

Write down details about the overall objective of the project:

  • Write the "executive summary" of the design in a few sentences in the Overview section of your design document. Explain what problem you're trying to solve, why you are trying to solve it, and who your target customers are. You may also want to talk about how this design helps achieve the team's long term vision.
  • Write a few key objectives in the Key Objectives section of the document. These are the high level "cardinal points" that outline the problem that needs to be solved. These objectives should drive further discussion as you drill down into the requirements, design, and implementation work.

For both the executive summary and the key objectives:

  • Apply the SMART criteria to help produce a high quality description of the objectives.
  • The objectives may evolve over the course of the design process. That's OK - to begin with, just capture your best understanding of the task at hand.

Conduct an informal early review

Edit Edit

For any project that's big enough to justify a design, you should usually conduct a review with your teammates and/or a subject matter expert who is aligned with your project. 

In general, it's advisable to conduct this review as early in the design process as possible, since this can save you significant time up-front. For example, if your objective is to implement a caching solution for your service, a senior developer may be able to point you to an existing solution or strategy that satisfies your use case -- potentially saving a large number of hours that would have been spent formulating requirements and creating designs that are actually not necessary.

That being said, use your best judgment. If it's too early to justify a review, then come back to it later. Perhaps you need to wait until some requirements are nailed down. You could also consider having a review at the beginning of the process to get guidance on the overall shape of the design, followed by a second review later to review the design when it's more fully fleshed out.

If I have seen further it is by standing on the shoulders of Giants.
- Isaac Newton

Determine requirements

Edit Edit

Determining requirements is essential for a good design. Clear requirements ensure that all stakeholders have a shared, agreed-upon understanding of what is (and is not) going to be implemented. Thorough and unambiguous requirements lead naturally to a high quality design and subsequently to an efficient, verifiable implementation.

Here are some basic ground rules to keep in mind when going through the requirements process:

  • Don't assume you know what the customer wants - always ask.
  • Involve the customer from the start.
  • Define and agree on the scope of the project.
  • Make sure requirements adhere to the SMART criteria.
  • Gain clarity if there is any doubt.
  • Avoid talking technology or solutions until the requirements are fully understood.
  • Get the requirements agreed upon with the stakeholders before implementation starts.
  • Create a prototype, if necessary, to confirm or refine the requirements.
  • Don't rely on anecdotes. Look to collect data to support (or disprove) anecdotes whenever possible.

Determining requirements can be broken down into 4 basic stages:

  1. Gather
  2. Define
  3. Prioritize
  4. Review

1. Gather

Edit Edit

As the designer, we may have a good idea of what the requirements for a project should be, but we may be looking at the problem in a particular way, and thus be unaware of the requirements that another stakeholder would call out.

For this reason, the designer should actively solicit requirements from the stakeholders - especially the most important stakeholder: the customer.

Here are some requirements gathering techniques. Use whichever ones make sense for the design.

Interview

Edit Edit

Interviewing customers and stakeholders is a great way to gather requirements. By understanding the perspective of each interviewee, you as the designer can properly articulate their interests in the form of requirements, and keep their priorities in mind when it comes to prioritization. 

The key strategy here is ask, then listen. Avoid trying to predict or tell the interviewee how to answer. Don't focus on what the feature might look like, focus on why we need it - get in the customer's shoes, understand their needs and pain.

Interviews can be formal (i.e. schedule a meeting) or casual (i.e. walk up to somebody's desk and ask them a question). Use your best judgment.

Prototype

Edit Edit

Creating a prototype or proof of concept is a good way to test out assumptions, clarify ambiguities, and prove or disprove the necessity of some requirement. 

When creating a prototype, keep in mind what you're trying to validate: if a low-fidelity whiteboard UI drawing will suffice, don't waste energy in setting up a new Rails server with Bootstrap. Identify the question you need to answer, do what you need to get the answer, then move on.

Prototypes in some situations can become official requirements, or can be turned into part of the design documentation.

Observe

Edit Edit

Observation means studying the customer's use of the software in their natural habitat. By watching users, you can uncover implicit requirements that might otherwise be overlooked, such as awkward workflows or other opportunities for improvement.

Depending on the design, observation can take a few different forms:

  • Active: ask a user to perform some task, then watch
  • Passive: look at data generated by users during regular usage, e.g. by analyzing log files
  • Focus groups: for larger/UI-focused designs, conducting a focus group can generate valuable and detailed requirements feedback.

Survey

Edit Edit

Sometimes you may need to gather data from a large number of people. It may be impractical to interview them in a timely and frugal manner. For this case, a questionnaire survey can be used. Work with the team to determine the proper audience, questions to ask, and method of advertising the survey.

Brainstorm

Edit Edit

Brainstorming is an efficient way to generate requirements, incorporating the interests of multiple stakeholders quickly.

  • Have a brainstorming session with up to 3 stakeholders (in addition to yourself), drawn from the following pool:
    • Customer
    • Dev team member
    • Team manager
    • Team member from a partner team
    • Senior developer from a sister team
    • Any other stakeholder
  • A hard limit of 4 people for this meeting is recommended to keep the discussion tightly focused. Too many participants can dilute the discussion at this stage. Additional stakeholders can contribute their thoughts in subsequent rounds.
  • The purpose of this brainstorming session is to discover requirements that are needed to satisfy the high level objectives. The group should also be willing to challenge and change the objectives themselves.
  • Consider drawing a mind map to facilitate brainstorming and focusing of the discussion. This approach can be very effective in quickly getting ideas articulated, from the general to the very specific.
  • Light discussion of implementation details are OK in the context of generating the right set of requirements. However, avoid drilling down too far into implementation specifics at this stage.
  • Don't worry about requirement priorities at this point. Let that wait until most of the requirements are actually defined and written down, as you'll then be able to understand the relative tradeoffs between all the requirements.

2. Define

Edit Edit

Write up the requirements discovered so far.

  • Adhere to the User Story syntax: As a X, I want Y, so that I can Z.
  • Adhere to the SMART criteria.
  • Avoid ambiguity. If a requirement isn't clear and concrete, consider using one of the following strategies to obtain clarity:
    • Talk through the requirement use case with a customer or other stakeholder. One effective approach is to talk through a real-life scenario where the requirement would apply, then try to show how the requirement does or doesn't make sense.
    • Create a prototype or proof of concept to prove or disprove the requirement, or test the assumptions that the requirement is based on.

Success Criteria

Edit Edit

At this point you should also write up the overall Success Criteria for the design, adhering to the SMART criteria model when doing so. 

  • These criteria should clearly articulate how we can determine when the implementation is complete.
  • When possible, define success thresholds in terms of concrete numbers and time scopes.

3. Prioritize

Edit Edit

Prioritize the requirements into one of the following categories using the MoSCoW method:

  • P0 "Must Have": considered non-negotiable requirements for satisfying the objective. The Minimum Viable Product (MVP) must satisfy all P0 requirements.
  • P1 "Should Have": requirements that are important to the objective, but might be skipped or deferred if they are deemed too expensive for the initial implementation effort.
  • P2 "Nice To Have": requirements that are a good idea, but should be treated as optional in terms of prioritization.
  • "Won't Have (this time)": requirements that are a good idea, but are out of scope for this design/iteration. Move these requirements to the Out of Scope section of your design document.

4. Review

Edit Edit

Review the requirements with stakeholders.

The objective here is to get sign-off from all relevant stakeholders. Getting sign-off is crucial to the success of the design: doing so ensures that all stakeholders understand the shape of the design and have explicitly bought into the plan.

The review is a good way to clarify ambiguous requirements, suss out additional requirements that may have been missed earlier, and refine the priorities.

You want all stakeholders to answer Yes to the following 3 questions:

  • Are the requirements clear? (There should be no doubt about what each requirement means)
  • Are the requirements complete? (Nothing should be missing)
  • Are the requirements correctly prioritized? (We should be doing the right things in the right order)

Reviewers should keep the SMART criteria in mind when doing the review.

Reviewers should not feel obligated to inject their opinions at this stage unless there is something that actually should be changed. Avoid focusing on superfluous aspects.

Depending on the outcome of the review, you may need to iterate on the requirements repeatedly. Keep at it until everybody is willing to sign-off on the above 3 questions.

Iterate on the design

Edit Edit

Fill in the different sections of your design document. The design document template provides some useful starting sections to think about when working through these details, but don't hesitate to add your own sections as you see fit.

The main theme of the design process should be kept in mind here: this is an iterative process. Fill in what you understand at this point, talk to stakeholders or peers to think through questions that come up, create prototypes and mockups, generate new requirements as needed, and get it reviewed when appropriate.

Conduct reviews

Edit Edit

Once the initial design effort is finished, and before starting on the implementation plan, we should conduct one or more reviews of the design to validate and verify it:

  • Validation: Are we building the right system?
  • Verification: Are we building the system right?

Which reviews you conduct are a judgment call by you and the team. As a general rule, all stakeholders should be in consensus about which reviews should be completed before moving forward.

UX review

Edit Edit

To collect feedback on UI designs, post UI mockups on the customer-facing SIM issue for review by customers.

We want to answer following questions:

  • Can the user understand what the feature is for?
  • Can the user figure out how to use the feature to complete a task?
  • Are there any features missing on the UI mockup?

Technical review

Edit Edit

Reviewers

Edit Edit

Identify at least two reviewers from the team. One of them should be a SME of your topic. If your project requires more than 4 dev weeks of implementation, invite a senior engineer to review your design. 

In-person review

Edit Edit

Any formal design should go through an in-person review. Reviewers may identify major issues at early stage and speed up the review process. This may not be a formal discussion. Depending on the design, this may be more of a whiteboarding session, asking for example, "This is the solution I have in mind. I considered these other two solutions but settled on this one. Does this seem like the right approach?"

Invite your reviewers and your team members (optional) to an one hour session. The review should focus on following major topics:

  • Architecture
  • Design rationales
  • Risks
  • User stories

Online review

Edit Edit

Once the design is updated with feedback from in-person review, send an online review request to other stakeholders who should be scoped in at this stage. This is to collect feedback for things missing in the in-person review and share knowledge with sister teams. The request should come with a deadline (2 days recommended). 

Create an implementation plan

Edit Edit

Write up the implementation plan and create corresponding issues in the issue tracker.

This plan should define all of the high-level milestones for the implementation effort. The design document template includes a basic implementation plan table to get you started. Feel free to add more details as you see fit.

The purpose of this plan is to establish an overall picture of the implementation effort and estimate how much work it will take. Now is not the time to actually schedule the work: scheduling is a team level process that needs to be done in consideration with other team priorities. Initially this plan just needs to enable the team to do that scheduling going forward.

When starting the implementation plan:

  • Create a master issue for the whole project
  • Link the master issue into the Implementation Plan section of the design document

For each milestone:

  • Create a sub-issue under your master  issue
  • Come up with an estimate in dev-weeks for the work
  • Record the milestone, including its issue link and estimate, in the design document

If a milestone is estimated at less than 1 dev-week, it might be a candidate for being merged into another/higher-level milestone. The goal here is just to establish a high level picture of the implementation effort for purposes of teamwide planning. Drilling down into the specific tasks for each milestone should be done separately by the team, outside of the design document.

Rely on your established requirements and Success Criteria when formulating the implementation plan. Once all milestones have been completed, you should be able to definitively declare that all the requirements and Success Criteria have been satisfied.

Once completed, review the implementation plan with the team manager, scrummaster, and/or other relevant stakeholders.

Deliverables

Edit Edit

The following items should be the output of the design process:

  • The design document, signed-off on by relevant stakeholders
  • The implementation plan, signed-off on by relevant stakeholders
  • Issue tracker - create issues for the project and each milestone in the implementation plan