Create design-document-template.md #203
Conversation
Create design document closes #202
|
I would not try to define here a design document template, unless we want to end with endless debates about that. Here is some info about the Design Documents at Google: Not because it is perfect, but because it is good enough, and I am familiar with it (vs looking for design documents on the web, reading / understanding / judging what they mean, and if they are good enough. If others can contribute something they know about, would be great. And note that it is not a "universal recipe" for design documents. That article say
We can point to design documents or "deep dive" documents from ICU4X as examples. What I think is critical to be in a design document that is not visible in code:
There is no need for code in a design document. The design document should rather contain pseudo-code to describe how things behave (not implementation), Code can be used as a prof that something can be implemented, can do what it claims to be doing, and help the designed figure out the proper public APIs |
There was a problem hiding this comment.
I don't think we need to create a design doc template, if we don't want to spend weeks on it.
We should point to a few good existing templates, and some examples of design documents.
Because design documents
"They are more what you'd call guidelines than actual rules"
https://imageproxy.ifunny.co/crop:x-20,resize:640x,quality:90x75/images/ef717be29ae4c022fa0fb844dcdf70dfd9fe7ca3bf770262a60ba4c5471b24ef_1.jpg
There was a problem hiding this comment.
Proposal
We should:
- point to 2-3 good existing templates
- point to some examples of design documents (ICU4X?)
- list 2-3 things that we really-really want to be part of the design doc, even if everything else is discarded / optional, to not make things too heavyweight
Yes. |
This is a PR with a proposal for a simple design doc. I suggest maybe having this as a base template and mention others that you listed there. The idea is only have something to get started with. |
| ### Motivation | ||
| Motivation to have this design document | ||
|
|
||
| ### Examples & Prior Art |
There was a problem hiding this comment.
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
|
|
||
| Discuss any background and motivation not already in the summary above. Give implementation details and all posible alternatives to solve the problem including affectations to other components. | ||
|
|
||
| ### Code / Implementation / Experiments |
There was a problem hiding this comment.
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.
| Discuss any background and motivation not already in the summary above. Give implementation details and all posible alternatives to solve the problem including affectations to other components. | ||
|
|
||
| ### Code / Implementation / Experiments | ||
| Code examples, alternative solutions |
There was a problem hiding this comment.
Code examples should only be about how the proposed APIs should look like when used, no internals.
| ## Design | ||
|
|
||
| Discuss any background and motivation not already in the summary above. Give implementation details and all posible alternatives to solve the problem including affectations to other components. | ||
|
|
There was a problem hiding this comment.
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.
Co-authored-by: Eemeli Aro <eemeli@gmail.com>
Add intro and other template links
| @@ -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: | |||
There was a problem hiding this comment.
Proposal for a design doc template
Create design document closes #202