Better design discussions

[Joseph Reynolds]

On 10/15/2018 4:44 PM, openbmc-request at lists.ozlabs.org wrote:
> Send openbmc mailing list submissions to
> 	openbmc at lists.ozlabs.org

This is a summary of an OpenBMC Community Call discussion held on 
2018-Oct-15.  I gave my advice for how to make our design discussions 
more approachable and easier to understand.  The advice is consistent 
with ideas discussed by the release planning workgroup and the testing 
workgroup.  The main idea is to use the new design template: 
https://github.com/openbmc/docs/blob/master/designs/design-template.md, 
specifically:
- record the problem that prompted you to create the design
- walk through functional scenarios in your design overview

The problems I am trying to solve include:
- It can be difficult to understand the context each design, that is, 
how it fits into the larger solution.
- It can be difficult to understand the value of each design, that is, 
what problem it solves.
- It can be difficult to understand the function of each design, that 
is, how to use it to solve a problem.

Details:

Why take time to document requirements and scenarios?
- Writing the requirements and walking through scenarios will sharpen 
your thinking about what problem you are trying to solve and how you 
plan solve it.
- You only need to explain your requirements once, and you won't have to 
repeat yourself.
- You'll be helping the uninitiated to understand your technical area.
- Your designs will be more approachable and easier to understand.
- You'll get better reviews which will give you a better design.
- Scenarios engage the reader and help explore your design.
- You'll learn how better requirements leads to better design, and how 
that leads to better code.

What exactly am I calling for?
- Requirements: Before you create new design, ask yourself what problem 
you are trying to solve, then write down the answer.  See the design 
template for ideas.
- Scenarios: When you have a design, walk through a few high-level 
scenarios, then write them down.  See 
https://en.wikipedia.org/wiki/Scenario_(computing).
- Collaborate: Be prepared to answer questions about the problem you are 
proposing to solve.  Also be prepared to explain how to use your design 
to solve the problem.

That's the only change I am calling for.

I also presented a negative scenario intended to illustrate the 
consequences of not having a good design process.  In this scenario, 
attackers dump bad designs onto the mailing list, then push buggy code 
into gerrit, and +1 their reviews.  I believe a good defense against 
this (and more subtle bugs) is a development community that creates 
strong links between requirements, design, and code.

Thank you,
- Joseph