Skip to content

Commit

Permalink
docs/RFCS: add section on using a narrative to README.md
Browse files Browse the repository at this point in the history
I used to have this bad habit when writing RFCs to not be
concise with my writing. Eventually, I was able to improve
that, but I noticed that feedback could still sometimes be
scarce. Eventually, I learned that my RFCs, even if concise,
usually consisted of a few abstract arguments, followed by
a list of technical specs and facts about the problem domain.

This type of writing can alienate prospective readers of
the RFC by making the document difficult to read. Writing
with eloquence & a strong, singular narrative can help
avoid this pitfall, which I've found leads to more reader
enagagement, and the RFC reaching a wider audience.

This commit updates the docs/RFCS/README.md with a new
section about presenting a narrative in your RFC. The
aim is for this to help future readers of the README
avoid similar pitfalls that I've experienced in the past.

Release note: none
  • Loading branch information
abarganier committed Jul 8, 2022
1 parent 96efa51 commit f8a8255
Showing 1 changed file with 23 additions and 0 deletions.
23 changes: 23 additions & 0 deletions docs/RFCS/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,29 @@ it forces bigger picture thinking which readers can then dissect. In
this respect an RFC is complimentary to a prototype which forces details
to be considered.

# Present a Narrative

When writing your RFC, you should always keep the prospective reader
in mind. We already mentioned above that one should do their best to
[keep things concise](#keep-it-concise), but what more can you do to
make the life of your reader easier?

As engineers & scientists, it can be tempting to use a large pile of
facts to state your case. After all, the facts don't lie, and if we
present enough of them in support of our cause, it helps strengthen
our argument. But is the reader going to enjoy reading a long laundry
list of facts? Probably not. However, if you are able to weave these
facts and technical designs together with a strong, singular narrative,
your writing is more likely to resonate with the reader.

Therefore, when writing your RFC, try to present your ideas with an
overarching narrative. Be clear about the problem(s) you're trying to
solve. Consider presenting some real-world examples to help make things
more relatable. Do your best to structure your writing in an eloquent way.
Taking such steps will help keep the reader engaged. This will likely
lead to your RFC being better received and gaining more attention, which
means you'll receive more feedback (a good thing!).

# Prototyping

There is a puzzle at the heart of writing an RFC: if you understand a
Expand Down

0 comments on commit f8a8255

Please sign in to comment.