Response to https://twitter.com/sarahmei/status/862479305590284288
Whenever we’re going to make a medium or big change (feature, refactor, etc.) we’re always encouraged to create a design doc before doing actual coding:
- Create a design doc.
- Have people review it and comment on it (we use Google docs of course 😅).
- Then finally start coding and sending the change lists (pull requests) for review.
The content and format of the docs changes a lot between people, but typically includes: issue/feature/task at hand, screenshots of mocks if it’s a GUI change, possible solutions/designs, high and low level descriptions and justification of the chosen one, code snippets or pseudocode, and sometimes diagrams.
Swift proposals are pretty close: https://github.com/apple/swift-evolution/tree/master/proposals. Other than that, the only articles that are somewhat close the the average Google design doc: https://people.eecs.berkeley.edu/~kubitron/courses/cs162-F06/design.html and http://blog.slickedit.com/2007/05/how-to-write-an-effective-design-document/.
What’s really cool is that it helps us:
- Gain the largest possible understanding before coding: bumping into edge cases, unexpected limitations because of some other code, minimizing oversights, etc.
- Get familiar with all the existing code that we’ll be dealing with.
- Get faster code reviews because time is no longer spent on design discussions.
- Along the same lines, design reviews don’t get mixed with reviews of the actual code, which I suspect must have its benefits.
- The docs provide very good historical context for people that bump into that code in the future, since they’re typically linked to in the change list (pull request) descriptions or code comments.
- Build-up written evidence and examples for why other sub-systems/frameworks/libraries need to be changed or replaced. (This typically comes up as part of possible solutions: “XYZ could be done, but system A does not allow X to be done at this time.”)