Request for Comments (RFC)
Propose and discuss changes using RFCs
Request for Comments (RFC)
RFCs are proposal documents that describe a significant change or feature, inviting team discussion and feedback before implementation.
What is an RFC?
A Request for Comments is a document that:
- Proposes a change, feature, or improvement
- Invites feedback from stakeholders
- Documents the discussion process
- Reaches a decision through consensus
RFCs are collaborative by nature. They're designed to gather input from the team before committing to a direction.
When to Write an RFC
Write an RFC when:
- ✅ Proposing a new feature
- ✅ Suggesting significant refactoring
- ✅ Changing team processes or standards
- ✅ Introducing new tools or technologies
- ✅ Any change that affects multiple team members
RFC Structure
A comprehensive RFC includes:
Title
Clear, descriptive title indicating the proposal.
Example: "RFC: Implement Real-time Collaboration"Summary
A brief overview (2-3 sentences) of the proposal.
Motivation
Why is this change needed?
- What problem does it solve?
- Who benefits from this change?
- What happens if we don't do this?
Detailed Design
The heart of the RFC:
- Technical approach
- Architecture changes
- API designs
- User experience changes
Alternatives Considered
What other approaches were evaluated?
- Why were they rejected?
- What are the trade-offs?
Implementation Plan
How will this be implemented?
- Phases or milestones
- Timeline estimates
- Resource requirements
Risks and Mitigations
What could go wrong?
- Potential risks
- How to mitigate them
Open Questions
What still needs to be decided?
- List unresolved issues
- Invite specific feedback
Example RFC
# RFC: Add Mermaid Diagram Support
## Summary
Add support for Mermaid diagrams in the document editor,
allowing users to create flowcharts, sequence diagrams,
and other visualizations using text-based syntax.
## Motivation
Technical documentation often requires diagrams. Currently,
users must create diagrams externally and embed images.
Mermaid support would allow:
- In-editor diagram creation
- Version-controlled diagrams (text-based)
- Easy updates without external tools
## Detailed Design
### Editor Integration
- Add Mermaid code block type to TipTap
- Render Mermaid syntax to SVG in preview
- Support common diagram types:
- Flowcharts
- Sequence diagrams
- Class diagrams
- State diagrams
### Syntax Example
```mermaid
graph TD
A[Start] --> B{Decision}
B -->|Yes| C[Action 1]
B -->|No| D[Action 2]Libraries
Use mermaid.js for rendering (BSD license).
Alternatives Considered
- PlantUML: More features but requires server-side rendering
- Draw.io embed: Too heavy, external dependency
- Image uploads only: Current approach, but not version-friendly
Implementation Plan
- Week 1: Add Mermaid dependency and basic rendering
- Week 2: Editor integration and syntax highlighting
- Week 3: Error handling and preview optimization
Risks
- Performance: Large diagrams may slow rendering
- Mitigation: Lazy render, debounce updates
- Syntax errors: Users may write invalid Mermaid
- Mitigation: Show helpful error messages
Open Questions
- Should we support all Mermaid diagram types?
- What's the maximum diagram size we should allow?
- Should diagrams be exportable as images?
## RFC Workflow
### 1. Draft Phase
- Write initial RFC
- Mark as **In Progress**
- Share with a small group for early feedback
### 2. Review Phase
- Publish to wider team
- Collect comments and feedback
- Update RFC based on input
### 3. Decision Phase
- Request sign-offs from stakeholders
- Address any rejections or concerns
- Iterate until consensus
### 4. Final Phase
- Mark as **Accepted** or **Closed**
- Communicate decision to team
- Begin implementation (if accepted)
## Best Practices
### Start a Discussion Early
- Don't perfect the RFC before sharing
- Early feedback saves time
### Be Open to Changes
- RFCs are living documents
- Update based on feedback
### Request Specific Feedback
- List open questions
- Tag relevant reviewers
### Set a Deadline
- Prevent indefinite discussion
- Move to decision after reasonable time
### Document Decisions
- Update RFC with final decisions
- Note why alternatives were rejected
## Creating an RFC in ArchDoc
1. Navigate to **Dashboard > Documents**
2. Click **New Document**
3. Select **RFC** as the document type
4. Enter a descriptive title
5. Write your proposal using the editor
6. Save and share for feedback
7. Request sign-offs when ready
8. Mark as Accepted or Closed
## Related
- [Creating Documents](/docs/documents/creating-documents)
- [Sign-off Workflow](/docs/signoff/overview)
- [Design Docs](/docs/documents/design-docs)