A repo for technical design documents
This repository is used for technical design reviews, inspired by this blog post.
Why do design reviews here instead of Google Docs?
- Visibility / Discoverability - Once you write the design review in Google Docs, it's usually left there, with minimal visibility for other people to find later. Here everyone can find and discover.
- Comments / Approval - We can leverage Github's powerful PR review / commenting flow.
- Versioning - We can use the powerful capabilities of Git to review previous versions of the design, and how it changed over time.
- Markdown - We can leverage Markdown's easy and clean formatting. You can learn the basics here and here.
- Templates - We can easily create templates for design documents.
- Always follow the naming conventions for filenames and folders.
- Create a folder for the design document under the relevant
pi-*folder. That folder will contain the markdown file and additionally any other resource you've included (pictures, graphs, etc...) - Open a PR and add the relevant stakeholders as reviewers so that they know about it.
- Do not follow the same rules / processes for team Git branches / PR names like we have for regular development. They don't make sense here. You can create a PR directly to main branch.
- Run Prettier on your markdown files, before you commit them. Otherwise, build will fail.
- Always include the source to the diagram so it's easily editable by anyone later.
- Use the template.
Diagrams are very important. They help convey your design much better than words and also help you create a better design.
Use Mermaid and their Live Editor to create all kind of flow diagrams. Include the diagram image in your design markdown file and always include link to the source so it's editable.
Use Excalidraw for whiteboard sketching diagrams. Also in this case, embed the image and include the source for your diagram in the markdown file.