Re:Design Docs at Google
by 010101010101 on Wednesday July 22, 2020 @08:33AM
(#23916246)
This is great. At my company we normally create design docs, and I’ve seen each of the anti-patterns described here, along with their more informative/useful counterparts, but not seen a place that succinctly enumerates “do/don’t do” very well.
A piece of feedback - I like to include sequence diagrams along side system diagrams to detail interactions a bit. I think this serves a similar purpose to documenting the API in an informal manner, and gives a good amount of information density (I _don’t_ expect everyone to read and digest all 5-15 pages of a document, pictures help people retain what’s important and also have a small thing to refer to in the future, IMO).
A piece of feedback - I like to include sequence diagrams along side system diagrams to detail interactions a bit. I think this serves a similar purpose to documenting the API in an informal manner, and gives a good amount of information density (I _don’t_ expect everyone to read and digest all 5-15 pages of a document, pictures help people retain what’s important and also have a small thing to refer to in the future, IMO).