How to write Request For Comments (RFC) documents?

Instead of imagining it as we need to do X doc for Y path, let's think about a RFC as a scenario working toward resolution.

1. You have a proposal that will impact the code surfaces of multiple people.
2. You want to make sure that the people impacted are aware of the changes and are comfortable having them made.
3. You write a document to explain the problem that is leading to the changes needing to be made, the changes being made, and the path of progression for making said changes.
4. You tag the people impacted on your doc and have them read it. Try to be exact with the tagging people on the exact changes that only impact them.
5. Go back and forth until they explicitly sign off (likely on a table on the doc).
6. Proceed with making the changes.

Lead with principles identifying the core problem first & work towards the outcome for the problem. Don't think about the exact terminology unless it makes communication with the people around you easier.

This course has a detailed technical design doc which I personally wrote: System Design Masterclass: Shipping Real Features To Production

It's old but the content still mostly holds up. It's on my roadmap to redo it and modernize it, but there are a lot of projects ahead of it 😅

I don't understand the difference between a Software Architecture document and a RFC. Are they the same?

It really depends on the company - Some places can be super finicky about lingo. From my perspective, RFC = request for comment, and like the name suggests, it's anything requesting a comment from a design doc to a pull request. So a software architecture document will RFC by default but not all RFCs are software architecture documents if that makes sense.

Software architecture documents go by many, many names depending on where you've worked:

• Tech docs
• Tech specs
• Design docs
• Technical design doc
• System design doc