Skip to content

Create design-document-template.md #203

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 3 commits into from
Closed

Create design-document-template.md #203

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e335be9
Create design-document-template.md
romulocintra Oct 5, 2021
cae099a
Apply suggestions from code review
romulocintra Oct 11, 2021
7710412
Update design-document-template.md
romulocintra Oct 11, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions guidelines/design-document-template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
<!--
This document intends to provide a simple boilerplate to start a design document, fields aren't strictly required and other templates can be found here:
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mihnita @eemeli added this header with some examples of Design Docs. The intention of this document is to have a boilerplate where people can start. Nevertheless, you can use whatever you like most. If you have any other Design Doc of reference I can add it to the list

- [Chromium Design Doc Template](https://docs.google.com/document/d/14YBYKgk-uSfjfwpKFlp_omgUq5hwMVazy_M965s_1KA/edit)
- [ICU4X Desing docs](https://github.com/unicode-org/icu4x/tree/main/docs/design)
- []
-->

# Design Document - My proposal

## Overview

### Motivation
Motivation to have this design document

### Examples & Prior Art
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would tag various sections with "optional" if it is ok to leave them out of the document.
We don't want a very bureaucratic thing and duck taping ("you left out X")

So, prior art: optional

Examples or references in how other solved similar or same problems

## Design

Discuss any background and motivation not already in the summary above. Give implementation details and possible alternatives to solve the problem including effects on other components.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What needs to be in a design document:

Goals and non-goals

Alternatives considered and trade-offs

Since we got to a design document it means there is no one solution that everybody agrees that is perfect.
So there are obviously trade-offs.

This would be the "meat" of the design document, as it explains how the trade-offs are balanced.

APIs (probably sub-section for each alternative in "Alternatives considered"

The APIs section should include signatures.
Should also include explanations on what they do, if not obvious.
Behavior described as pseudo-code.
But behavior is not implementation.

It is also useful to show how the APIs are invoked by the developer, the proper sequence in normal use.

### Code / Implementation / Experiments
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code , implementation, should NOT be in a design document.

Implementation is only needed to prove that something can be implemented as proposed.
If nobody says "this can't be done" or "this would not work", then there is no need for implementation.

And if it is needed, then it is in some repo, with the design document pointing to it "it's possible, here it is"
But no code / implementation in the design doc.

Code examples, alternative solutions
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code examples should only be about how the proposed APIs should look like when used, no internals.


### References/Links
Link to mocks, specs, and related features.

## Follow up

### Consensus
List decisions or agreements

### Meeting notes
Link to meeting notes or add them inline