Issues-Driven Specifications

What

  • An approach centered around questions ("issues") to create and refine product & tech specifications
  • A series of principles to ask questions and find their answers to reach high-quality specs
  • Processes & templates (Notion) to put this into practice

Why

  • Increases overall level of quality through better knowledge of problem and solution domain
  • Fosters involvement from team members and organization at large
  • Fosters critical thinking within the team, tackling each issue with the same level of quality as an ADR
  • Increases efficiency of specs and dev processes through async writing
  • Avoid bad suprises by leaving no stone unturned, surfacing implicit assumptions, and explicitly ensuring team alignment
  • Saves time for members that are punctually involved, by giving them full context (e.g. managers, external devs, other stakeholders)
  • Creates documentation along the way

When, how and who ?

  • Do as soon as you start converging on product and tech needs
  • Continuously maintain and refer to questions during implementation (e.g., point to issue in US)
  • Jointly maintained by PM and EM / Tech lead
  • Notion

Examples

Principles

Crafting questions

  • MECE: with focus on CE
  • Divide and conquer: aim for atomic questions, refacto them into subquestions if discussions are drifting
  • Eigenquestions: reduce problems to their essence (e.g., try to reframe problems as problems of choosing between principles rather than solutions)

Answering questions

  • Answer-first: the asker should always try to already provide an answer to catalyze discussions
  • No complacency: list all scenarios with their pros and cons, be explicit when you exclude something
  • Remove egos from the equation: avoid linking answers and proposals to their creator, decouple people and ideas to ease reflections (e.g. if we say "I prefer John's idea over Ruth's", Ruth might be tempted to be contrarian if she dislikes John)
  • Next obvious question: often answering a question will raise another question, especially at the beginning. Be on the lookout for this and capture new questions immediately and proactively

In practice

  • Simple list of issues
  • Driving an async meeting around issues
  • Exposing issues through linked databases
  • Converging
  • Using issues during development

Do's & Don'ts

Do

  • Use a template
  • Use Notion commenting system
  • Force people on Slack to open issues instead
  • Refer to issues all the time when already answered
  • Create issues DB per big domain (mkting, product, engineering)
  • Explore creative usage (at Canyon, we did it for fundraising, HR...)

Don't

  • Use inline text
  • Be rigid about statuses
  • Get sad if many issues become obsolete

Pitfalls

  • Maintainability
  • Duplicates
  • Overwhelming, must be accompanied by executive summary that are regularly updated
  • Can feel heavy when you force atomic questions
  • Does not scale super well beyond squad of max 10 people