github.com/cockroachdb/cockroach@v20.2.0-alpha.1+incompatible/docs/RFCS/PROTOTYPING.md (about)

     1  # Prototyping and RFCs
     2  
     3  There is a puzzle at the heart of writing an RFC: if you understand a
     4  project well enough to write an RFC, then an RFC may not be
     5  necessary. Certainly you may write an RFC to communicate your
     6  knowledge to others, but how does an RFC get written by an individual
     7  who doesn't understand the problem fully?
     8  
     9  The idealistic view of writing an RFC involves an engineer starting
    10  with a blank document and filling in the pieces from start to
    11  finish. For anyone who has written an RFC, this fairy tale depiction
    12  is clearly not accurate. The writing is iterative. You might first
    13  write down a few bullet points and then start thinking about the
    14  details of one area, fleshing out the document incrementally and in an
    15  unordered fashion. There are very likely many (many) iterations of the
    16  document before anyone else takes a look at it.
    17  
    18  The iterative writing of an RFC described above is often insufficient
    19  because simply thinking deeply about a problem is frequently not the
    20  most efficient path to fully understanding the problem. At the very
    21  least you will be consulting the existing code base to understand how
    22  the proposed change fits. And you might discuss the problem in front
    23  of a whiteboard with a colleague. It is very likely you should be
    24  prototyping.
    25  
    26  Prototyping involves exploring a problem space in order to better
    27  understand it. The primary value of a prototype is in the learning it
    28  provides, not the code. As such, the emphasis during prototyping
    29  should be on speed of learning. The prototype code does not need to
    30  meet any particular quality metric. Error handling? Ignore it while
    31  you're trying to learn. Comments? Only if you, the prototype author,
    32  need them. The real focus of the prototype is exploring the unseen
    33  corners of the problem space in order to reveal where the dragons are
    34  lurking. The goal is to de-risk the problem space by thoroughly
    35  understanding the hardest problems.
    36  
    37  The acts of prototyping and writing an RFC should be iterative. Many
    38  engineers want to write down their thoughts before coding and it is
    39  common to want to discuss an approach before embarking on it. Both
    40  approaches are useful, yet neither should be confused for an RFC. It
    41  is useful to write down a few bullet points for areas to be covered in
    42  a prototype. Then work on the code. Then add more bullet points. At
    43  some point, the prototype will be fleshed out enough that you feel
    44  ready to write the RFC. Alternately, it is very common for the
    45  prototype to run into a significant stumbling block that you can't
    46  overcome yourself. The benefit of the prototype truly shines when this
    47  happens and you'll have a deep understanding of the problem which you
    48  can use to have a focused discussion with other engineers. Share your
    49  failed prototypes. The failure implies learning and that learning
    50  deserves to be shared, both in words and in code. Your failed
    51  prototype might be close to success with the aid of another engineer's
    52  experience. At the very least, a failed prototype indicates to other
    53  engineers that an idea has been explored.
    54  
    55  An RFC is a high-level description which does not require formal
    56  correctness. There is utility in conciseness. Do not overspecify the
    57  details in the RFC as doing so can bury the reader in minutiae. The
    58  prototype can be of assistance here as it can help highlight the
    59  tricky areas that deserve mention in a high-level description. If the
    60  details are relevant, the RFC can include a link to the prototype
    61  (which may necessitate cleaning up some of the prototype code at the
    62  reviewer's request). Note that one of the significant benefits of an
    63  RFC is that it forces bigger picture thinking which readers can then
    64  disect. In this respect an RFC is complimentary to a prototype which
    65  forces details to be considered.
    66  
    67  Writing an RFC is not a necessary outcome for a successful
    68  prototype. If the prototype is simple enough, it can be translated
    69  directly into a PR or series of PRs along with explanatory comments
    70  and commit messages.