<story><title>Design Docs at Google</title><url>https://www.industrialempathy.com/posts/design-docs-at-google/</url></story><parent_chain><item><author>nickbauman</author><text>This is something that should be taught to folks while they&amp;#x27;re still in school. The &amp;quot;blueprint analogy&amp;quot; has baked in the idea that there&amp;#x27;s a &amp;quot;design phase&amp;quot; and a &amp;quot;construction phase&amp;quot; and that these are often discreet parties.&lt;p&gt;Nothing could be more incorrect when it comes to software. In software, &lt;i&gt;the design is the code.&lt;/i&gt; The compiler&amp;#x2F;interpreter are the construction of the system.</text></item><item><author>sarchertech</author><text>&amp;gt;If code is the bricks and mortar, then these docs are the blueprints.&lt;p&gt;That analogy falls apart quickly. Design docs aren’t specific enough to be analogous to blueprints.&lt;p&gt;You can give a set of blueprints to 3 different construction firms and get fundamentally the same building. Try giving design docs to 3 different development shops and see what happens.&lt;p&gt;The problem is that the only way to get to that level of specificity is with code.&lt;p&gt;Design docs are closer to something a city planner would produce than to something an architect or civil engineer would, and they should be treated accordingly.</text></item><item><author>cameronbrown</author><text>Design docs are one of my favourite things about software engineering. If code is the bricks and mortar, then these docs are the blueprints.&lt;p&gt;I know this is fairly controversial, but our jobs isn&amp;#x27;t just to write code. Navigating organisations and achieving consensus between a lot of teams&amp;#x2F;technologies is a huge part of it.&lt;p&gt;Design docs are a way to get all of that out of the way _before_ writing thousands of lines of code. The review process nets significantly different feedback to code reviews too.</text></item></parent_chain><comment><author>throwaway_pdp09</author><text>&amp;gt; In software, the design is the code. The compiler&amp;#x2F;interpreter are the construction of the system.&lt;p&gt;That&amp;#x27;s IMO a pedantic view. Yes, ok, but when I design software I describe it&amp;#x27;s high-level characteristics, more like describing the plot of a book than the specific words in a book and the what the characters say to each other.&lt;p&gt;I&amp;#x27;d say there are many levels of design. Code is the last.</text></comment>
<story><title>Design Docs at Google</title><url>https://www.industrialempathy.com/posts/design-docs-at-google/</url></story><parent_chain><item><author>nickbauman</author><text>This is something that should be taught to folks while they&amp;#x27;re still in school. The &amp;quot;blueprint analogy&amp;quot; has baked in the idea that there&amp;#x27;s a &amp;quot;design phase&amp;quot; and a &amp;quot;construction phase&amp;quot; and that these are often discreet parties.&lt;p&gt;Nothing could be more incorrect when it comes to software. In software, &lt;i&gt;the design is the code.&lt;/i&gt; The compiler&amp;#x2F;interpreter are the construction of the system.</text></item><item><author>sarchertech</author><text>&amp;gt;If code is the bricks and mortar, then these docs are the blueprints.&lt;p&gt;That analogy falls apart quickly. Design docs aren’t specific enough to be analogous to blueprints.&lt;p&gt;You can give a set of blueprints to 3 different construction firms and get fundamentally the same building. Try giving design docs to 3 different development shops and see what happens.&lt;p&gt;The problem is that the only way to get to that level of specificity is with code.&lt;p&gt;Design docs are closer to something a city planner would produce than to something an architect or civil engineer would, and they should be treated accordingly.</text></item><item><author>cameronbrown</author><text>Design docs are one of my favourite things about software engineering. If code is the bricks and mortar, then these docs are the blueprints.&lt;p&gt;I know this is fairly controversial, but our jobs isn&amp;#x27;t just to write code. Navigating organisations and achieving consensus between a lot of teams&amp;#x2F;technologies is a huge part of it.&lt;p&gt;Design docs are a way to get all of that out of the way _before_ writing thousands of lines of code. The review process nets significantly different feedback to code reviews too.</text></item></parent_chain><comment><author>supahfly_remix</author><text>If the design is the code, then what is a bug?  There is a separate model, whether written down or not, of what the code must do.  That is the deaign.</text></comment>