commit 78ae68560be14c711990481f88017d99ebe57e45
author Edwin Kempin <ekempin@google.com> Thu Aug 01 15:27:44 2019 +0200
committer Edwin Kempin <ekempin@google.com> Mon Aug 05 09:37:52 2019 +0200
tree a0c84e88b188f752f8823b42ecf898ab31e74af8
parent 29012f079a5c97f2633f5a4d2f9d0178ce7e2897

Make writing design docs more collaborative and iterative

When we introduced the design-driven contribution process we started
with a simple process and template for writing design docs, with the
intention to refine the process and template later. Now we gathered some
first experience with design discussions and we noticed/foresee a few
things that are not optimal yet, hence we want to improve the process
and the template.

Things that we want to improve:

1. Agreeing on a solution is difficult and design reviews can take a
   long time. At the moment a design doc can only be submitted once
   everyone agrees on the proposed solution.
2. If alternative solutions are proposed in comments they may not get
   the amount of attention that they deserve.
3. It is seen as the responsibility of the design doc author to pick up
   newly suggested alternative solutions and include them into the
   design doc, but it's hard for the author to parse proposed solutions
   from review comments and describe them accurately and with details in
   the design doc.
4. If newly suggested alternative solutions get included into the design
   doc they likely end up in the 'Alternatives Considered' section,
   which makes them look less favored than the solution that was
   initally advertised in the design doc.
5. Picking up a newly suggested solution as the new main solution
   requires rewriting large parts of the design doc (hence there may be
   some resistence against doing this).
6. There may be a tendency to favor the initially proposed solution
   since more work was going into it and alternative solutions are only
   briefly described.
7. Unrelated issues that are identified in design discussions tend to be
   ignored and forgotten.

Our goal with design discussions was to collaborate as much as possible
and to write design docs together, in an iterative manner. With the
current process and template this is not working well. To improve this
we suggest to split design docs into multiple files that can be written
and refined by several persons in parallel:

* index.md:
  Entry file that links to the files below.
* use-cases.md:
  Describes the use-cases, acceptance criteria and background.
* solution-<n>.md:
  Each possible solution (with the pros and cons, and implementation
  details) is described in a separate file.
* conclusion.md:
  Describes the conclusion of the design discussion.

It is expected that:

* An agreement on the use-cases is achieved before solutions are being
  discussed in detail.
* Anyone who has ideas for an alternative solution uploads a change
  with a solution-<n>.md that describes their solution.
* All possible solutions are fairly discussed with their pros and cons,
  and treated equally until a decision is made.
* Unrelated issues that are identified during discussions are extracted
  into new design docs (initially consisting only of an index.md and a
  use-cases.md file).
* Changes making iterative improvements can be submitted frequently
  (e.g. additional uses-cases can be added later, solutions can be
  submitted without describing implementation details, etc.).

In addition some aspects of the documentation which were outdated have
been adapted to reality:

* Design docs are written in Markdown, not Asciidoc (hence the templates
  were migrated).
* Design docs are reviewed and stored in the homepage repo, not in the
  gerrit repo.

Furthermore some minor improvements were done:

* It is now recommended to use the 'dir' query operator to watch
  design doc changes ('dir:pages/design-docs'), since it's more reliable
  than the 'hashtag' operator which was suggested before since people
  tend to forget to set this hashtag.
* Call out in the template for use-cases that Google-specific uses cases
  should be clearly marked as such (the Google setup is pretty different
  and not making this transparent can confuse readers).
* The design docs now talk about use-cases and acceptance criteria
  instead of objectives, since formulating use-cases forces the author
  to think from the users perspective and it's easier for reader to
  understand how users are affected.
* The period in which the ESC is expected to comment on newly proposed
  features was increased to 14 calendar days. This allows the ESC to
  discuss the proposal in the ESC meeting, which happens bi-weekly,
  before commenting on it.

Signed-off-by: Edwin Kempin <ekempin@google.com>
Change-Id: I401d5ec21ff2b568dab7346db212c9166537dfa9