4 ms·
Design docs should be written in Markdown and stored in git. The advantage here is that the git hash can be used as a legal reference, for example in the case
by jhallenworld 6y ago
Design docs should be written in Markdown and stored in git. The advantage here is that the git hash can be used as a legal reference, for example in the case where a contractor is expected to implement the design.
- dilyevsky 6y agoI’ve tried this and I tried just gdocs like everyone at google did. Gdocs seems better for iterating because github review ui sucks (and everyone else sucks even more). If google critique was publicly available I’d much prefer markdown for designs
- pmb 6y agoThe best is to get agreement on the design is gdocs and then export it to Github so that the design and code live next to each other.
- bbeekley 6y agoWe did this at a previous company in the healthcare space. It made audits easy since we could point to every instance of the design changing, who approved it, and the code that implements the change (all wrapped up in PR(s)). In general I like checking docs into source control, for all the reasons we use git and code reviews for the code itself.