There are as many ways to write an RFC, tech design, proposal doc, as there are ways to skin a cat. Here's the structure I'm currently using.
It looks a bit heavyweight, but it's possible to skip or collapse sections in less formal environments. But it's still useful as a framework for thinking through the proposal
- Title
- Usually a table of metadata like purpose, author, related documents, slack channel etc
- Introduction
- What system are we talking about, what's happening
- Objectives
- Primary and secondary objectives for what the proposal aims to solve / improve
- Baseline
- Current situation, solution, its architecture, traffic level
- Current problems, really these should have some kind of measurable numbers
- Target state
- Describe where we want to go: new architecture, way of working, technical change
- Target numbers for the problems, SLOs, reliability levels etc
- Key challenges
- List the difficult sticking points and how we expect to solve them
- It can be worth numbering these eg C1, C2...
- Delivery plan
- Using N engineers we expect to get this done by time T
- List of milestones: when and what (and benefit)
- Milestone breakdown
- Dependencies
- What are we depending on from external folks?
- Worth numbering D1, D2...
- Risks
- Risks to the delivery that are out of our company's control
- Risks from the change itself
- List with numbers R1, R2...
- Mitigations
- A table of risks / dependencies (D1, D2, R1 ...) and their mitigations
- Out of scope
- Explicitly list things that are out of scope
- Appendix
- Sections with all the numbers, data that backs up the document etc