Move drawbacks section up to a place of prominence, rework a few other section orderings
@@ -75,6 +75,15 @@ should go into the following sections.
This section is for explicitly listing the motivation, goals and non-goals of
this proposal. Describe why the change is important and the benefits to users.
+### User Stories
+
+Detail the things that people will be able to do if this is implemented.
+Include as much detail as possible so that people can understand the "how" of
+the system. The goal here is to make this feel real for users without getting
+bogged down.
+
+Include a story on how this proposal will be operationalized: lifecycled, monitored and remediated at scale.
+
### Goals
Summarize the specific goals of the proposal. How will we know that
@@ -89,6 +98,16 @@ focus discussion and make progress. Highlight anything that is being
deferred to a later phase of implementation that may call for its own
enhancement.
+## Drawbacks
+
+The idea is to find the best form of an argument why this enhancement should
+_not_ be implemented.
+
+What are the reasons we might not want to undertake this proposal, and how do
+we overcome them? Does this proposal implement a behavior that's new/unique/novel?
+Is it poorly aligned with existing user expectations? Will it be a significant
+maintenance burden? Is it likely to be superceded by something else in the near future?
+
## Proposal
This is where we get down to the nitty gritty of what the proposal
@@ -99,14 +118,6 @@ implementation that is proposed here, and expand on reasons for not
choosing alternatives in the Alternatives section at the end of the
document.
-### User Stories
-
-Detail the things that people will be able to do if this is implemented.
-Include as much detail as possible so that people can understand the "how" of
-the system. The goal here is to make this feel real for users without getting
-bogged down.
-
-Include a story on how this proposal will be operationalized: lifecycled, monitored and remediated at scale.
### API Extensions
@@ -373,10 +384,6 @@ Describe how to
Major milestones in the life cycle of a proposal should be tracked in `Implementation
History`.
-## Drawbacks
-
-The idea is to find the best form of an argument why this enhancement should _not_ be implemented.
-
## Alternatives
Similar to the `Drawbacks` section the `Alternatives` section is used to
