Note page to drop all interestign articles on the topic
Building up an engineering writing culture through design docs/rfcs.
- Time efficiency. Sharing ideas through writing eliminates the need for repetitive verbal updates to disseminate ideas and information.
- Knowledge sharing. Documenting important ideas forces clarity of thought and makes information more accessible to everyone in the company, versus slide decks that are ephemeral and require less rigor of thought.
- Communication. Clear writing requires clear thinking, meaning employees invest more time shaping their ideas before sharing them.
- https://slab.com/blog/stripe-writing-culture/
- https://increment.com/planning/planning-with-requests-for-comments/
- https://handbook.sourcegraph.com/company-info-and-process/communication/rfcs/
- https://martinfowler.com/articles/scaling-architecture-conversationally.html
- https://blog.pragmaticengineer.com/scaling-engineering-teams-via-writing-things-down-rfcs
- https://writingcooperative.com/the-anatomy-of-an-amazon-6-pager-fc79f31a41c9
- https://docs.google.com/document/d/167WV_rhBg3oj0yw9fHwUMlB-8BR3ktk2FSsKiUQo55Y/edit
- https://drive.google.com/drive/folders/1zP3FxdDlcSQGC1qvM9lHZRaHH4I9Jwwa
- https://www.industrialempathy.com/posts/design-docs-at-google/
- https://www.lennysnewsletter.com/p/my-favorite-templates-issue-37 (Product)
- https://newsletter.pragmaticengineer.com/p/software-engineering-rfc-and-design
- https://blog.pragmaticengineer.com/scaling-engineering-teams-via-writing-things-down-rfcs/
Typical structure for services:
- List of approvers
- Abstract (what is the project about?)
- Architecture changes
- Service SLAs
- Service dependencies
- Load & performance testing
- Multi data-center concerns
- Security considerations
- Testing & rollout
- Metrics & monitoring
- Customer support considerations
Typical structure for mobile:
- Abstract (what is the project about?)
- UI & UX
- Architecture changes
- Network interactions detailed
- Library dependencies
- Security concerns
- Testing & rollout
- Analytics
- Customer support considerations
- Accessibility
- Context and scope
- Goals and non-goals
- The actual design
- System-context diagram
- APIs
- Data storage
- Code and pseudo-code
- Degree of constraint
- Alternatives considered
- Cross-cutting concerns