summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorPatrick Venture <venture@google.com>2018-10-19 10:47:27 -0700
committerPatrick Venture <venture@google.com>2018-10-19 10:48:53 -0700
commitad3becf99e1a88a91c507a190baf9d80000e55a8 (patch)
tree17fa47b2f636a4d8cf2088486a26671ec6f7e017
parent318d9707f53515dabd1242e6d620052c69f1a75a (diff)
downloadopenbmc-docs-ad3becf99e1a88a91c507a190baf9d80000e55a8.tar.gz
openbmc-docs-ad3becf99e1a88a91c507a190baf9d80000e55a8.zip
design-template: reduce heading depth
Reduce heading depth from the start to reduce depth of sub-headings in detailed design. As the designs are meant to stand alone, they do not need an explicit initial depth of 3. Change-Id: Ib037c2da81962d7b5bee8dc01916e1269e189e5e Signed-off-by: Patrick Venture <venture@google.com>
-rw-r--r--designs/design-template.md18
1 files changed, 9 insertions, 9 deletions
diff --git a/designs/design-template.md b/designs/design-template.md
index 76cc0f1..c730132 100644
--- a/designs/design-template.md
+++ b/designs/design-template.md
@@ -1,5 +1,5 @@
____
-### Design Guidelines - *Delete this section*
+# Design Guidelines - *Delete this section*
* Not all new features need a design document. If a feature can be
contributed in a single reasonably small patchset that has little impact
@@ -23,7 +23,7 @@ ____
will also allow inline feedback on the diagram itself.
____
-### Example design - this is the design title
+# Example design - this is the design title
Author:
< Name and IRC nic >
@@ -34,14 +34,14 @@ Other contributors:
Created:
< Date initially created, revisions in will be tracked in Gerrit >
-#### Problem Description
+## Problem Description
(1 paragraph) What are we doing and why? What problem are you trying to
solve? What are the goals and NON-goals? Please make the objective
understandable for someone unfamiliar with this project by including the
necessary context, but keep it short. Elaborate on the details below in the
Background and Requirements sections.
-#### Background and References
+## Background and References
(1-2 paragraphs) What background context is necessary? You should mention
related work inside and outside of OpenBMC. What other Open Source projects
are trying to solve similar problems? Try to use links or references to
@@ -51,7 +51,7 @@ go bad. Include a glossary if necessary. Note: this is background; do not
write about your design, specific requirements details, or ideas to solve
problems here.
-#### Requirements
+## Requirements
(2-5 paragraphs) What are the constraints for the problem you are trying to
solve? Who are the users of this solution? What is required to be produced?
What is the scope of this effort? Your job here is to quickly educate others
@@ -59,7 +59,7 @@ about the details you know about the problem space, so they can help review
your implementation. Roughly estimate relevant details. How big is the data?
What are the transaction rates? Bandwidth?
-#### Proposed Design
+## Proposed Design
(2-5 paragraphs) A short and sweet overview of your implementation ideas. If
you have alternative solutions to a problem, list them concisely in a bullet
list. This should not contain every detail of your implementation, and do
@@ -67,15 +67,15 @@ not include code. Use a diagram when necessary. Cover major structural
elements in a very succinct manner. Which technologies will you use? What
new components will you write? What technologies will you use to write them?
-#### Alternatives Considered
+## Alternatives Considered
(2 paragraphs) Include alternate design ideas here which you are leaning away
from. Elaborate on why a design was considered and why the idea was rejected.
Show that you did an extensive survey about the state of the art. Compares
your proposal's features & limitations to existing or similar solutions.
-#### Impacts
+## Impacts
API impact? Security impact? Documentation impact? Performance impact?
Developer impact? Upgradability impact?
-#### Testing
+## Testing
How will this be tested? How will this feature impact CI testing?
OpenPOWER on IntegriCloud