Skip to content

Latest commit

 

History

History
73 lines (43 loc) · 3.13 KB

0000-00-00_template.md

File metadata and controls

73 lines (43 loc) · 3.13 KB
Raw

Template

Feel free to copy this file and feel all the details below. If you want to start in Google Doc, feel free to use similar Google Doc template. You can then use tooling like Docs to Markdown to translate your document.

See README for details.

Your Proposal Title

  • Owners:

    • <@author: single champion for the moment of writing. No need to add contributors all will be visible in commit or comments history on GitHub.>

  • Implementation Status: Not implemented / Partially implemented / Implemented

  • Related Issues and PRs:

    • <GH Issues/PRs>

  • Other docs or links:

    • <Links…>

TL;DR: Give here a short summary of what this document is proposing and what components it is touching. Outline rough idea of proposer's view on proposed changes.

For example: This design doc is proposing a consistent design template for “example.com” organization.

Why

Put here a motivation behind the change proposed by this design document, give context.

For example: It’s important to clearly explain the reasons behind certain design decisions in order to have a consensus between team members, as well as external stakeholders. Such a design document can also be used as a reference and knowledge-sharing purposes. That’s why we are proposing a consistent style of the design document that will be used for future designs.

Pitfalls of the current solution

What specific problems are we hitting with the current solution? Why it’s not enough?

For example, We were missing a consistent design doc template, so each team/person was creating their own. Because of inconsistencies, those documents were harder to understand, and it was easy to miss important sections. This was causing certain engineering time to be wasted.

Goals

Goals and use cases for the solution as proposed in How:

  • Allow easy collaboration and decision making on design ideas.
  • Have a consistent design style that is readable and understandable.
  • Have a design style that is concise and covers all the essential information.

Audience

If not clear, the target audience that this change relates to.

Non-Goals

  • Move old designs to the new format.
  • Not doing X,Y,Z.

How

Explain the full overview of the proposed solution. Some guidelines:

  • Make it concise and simple; put diagrams; be concrete, avoid using “really”, “amazing” and “great” (:
  • How you will test and verify?
  • How you will migrate users, without downtime. How we solve incompatibilities?
  • What open questions are left? (“Known unknowns”)

Alternatives

The section stating potential alternatives. Highlight the objections reader should have towards your proposal as they read it. Tell them why you still think you should take this path [ref]

  1. This is why not solution Z...

Action Plan

The tasks to do in order to migrate to the new idea.

  • Task one
  • Task two ...