<story><title>Why I close pull requests</title><url>http://www.jeffgeerling.com/blog/2016/why-i-close-prs-oss-project-maintainer-notes</url></story><parent_chain><item><author>fdsfsaa</author><text>Requiring permission to do work is the enemy of progress and engineering dignity. It creates a presumption of incompetence and an atmosphere of low trust that punishes people who want to push the envelope of what&amp;#x27;s possible.&lt;p&gt;Google&amp;#x27;s design document culture is bad. Google has succeeded in spite of it.&lt;p&gt;In my experience, having worked at many large tech companies, design documents obfuscate, not enlighten. They become increasingly out-of-date as the code evolves, creating anti-documentation that makes it take longer to understand code. Yes, yes, people should update design documents as the code evolves. Everyone knows that in practice, nobody updates old design documents.&lt;p&gt;Design documents make it too easy for other developers to shoot down ideas. Sometimes the worth of code isn&amp;#x27;t apparent until it&amp;#x27;s made. It&amp;#x27;s far too easy for someone to comment &amp;quot;this will never work&amp;quot; on a proposed change. It&amp;#x27;s much harder for someone to deny benchmarks attached to a proposed change. It&amp;#x27;s too easy for reviewers to knock out functionality.&lt;p&gt;Design documents turn every feature into a half-assed, lowest-common-denominator risk-minimized barely-adequate shell of itself.&lt;p&gt;The real reason everyone at Google writes design documents is that promotion committees demand documents as &amp;quot;evidence of complexity&amp;quot;. No design document, no impact. No impact, no promotion.&lt;p&gt;Code is just code. Bad changes can be backed out. It&amp;#x27;s much better to move fast and iterate quickly than to create an illusion of care and add friction to every aspect of the development process. Up-front design of software just does not work. If it did, waterfall project planning would be successful.&lt;p&gt;These questions you highlight --- Why are you making this change? What impact will it have? --- can be asked during review of actual code. There is no need to build a speedbump, not if you trust your people.&lt;p&gt;Developers should be able to &lt;i&gt;choose&lt;/i&gt; to create design documents and solicit feedback. Most changes don&amp;#x27;t need this process. You should trust developers to know what changes require a more extensive discussion and which ones don&amp;#x27;t.&lt;p&gt;A culture that requires permissions and signoffs before work can begin is a culture that leaves products stagnant for years.</text></item><item><author>yegle</author><text>At Google, if you want to implement new features (or large refactoring), you&amp;#x27;ll need to write a design doc. In which, you should answer questions your reviewers might ask (common questions like: why do you want to do this, what are the alternatives, how components interactive with each other before&amp;#x2F;after your change). This is something like Python&amp;#x27;s PEP: you need a proposal to convince your reviewer that you have put thought into your change.&lt;p&gt;Real world examples of these design docs can be found at &lt;a href=&quot;https:&amp;#x2F;&amp;#x2F;github.com&amp;#x2F;golang&amp;#x2F;proposal&quot; rel=&quot;nofollow&quot;&gt;https:&amp;#x2F;&amp;#x2F;github.com&amp;#x2F;golang&amp;#x2F;proposal&lt;/a&gt;</text></item></parent_chain><comment><author>tytso</author><text>At least in the part of Google where I work (Technical Infrastructure), in general most of the obvious optimizations that can be made at only one level (within the scope of a single programmer, or a single team), have been made long ago.   So most of the changes to make the system more efficient will require coordinated changes across multiple teams, and multiple pieces of software, and in some cases, may impact more than one SRE team.&lt;p&gt;In that kind of situation, you betcha we need to have design docs!   And in terms of making it easy for other developers to shoot down ideas, very often they may know about some dependency or key assumption in some other piece of code that you didn&amp;#x27;t know about it.   And it&amp;#x27;s better to find out about it during the design phase, than to have to rework 50% of your work when you find out about it at code review time, or worse, if it gets deployed and you get angry notes from SRE&amp;#x27;s that were woken up at 3am and you need to send them a bottle of whiskey to apologize for your f*ck up....</text></comment>
<story><title>Why I close pull requests</title><url>http://www.jeffgeerling.com/blog/2016/why-i-close-prs-oss-project-maintainer-notes</url></story><parent_chain><item><author>fdsfsaa</author><text>Requiring permission to do work is the enemy of progress and engineering dignity. It creates a presumption of incompetence and an atmosphere of low trust that punishes people who want to push the envelope of what&amp;#x27;s possible.&lt;p&gt;Google&amp;#x27;s design document culture is bad. Google has succeeded in spite of it.&lt;p&gt;In my experience, having worked at many large tech companies, design documents obfuscate, not enlighten. They become increasingly out-of-date as the code evolves, creating anti-documentation that makes it take longer to understand code. Yes, yes, people should update design documents as the code evolves. Everyone knows that in practice, nobody updates old design documents.&lt;p&gt;Design documents make it too easy for other developers to shoot down ideas. Sometimes the worth of code isn&amp;#x27;t apparent until it&amp;#x27;s made. It&amp;#x27;s far too easy for someone to comment &amp;quot;this will never work&amp;quot; on a proposed change. It&amp;#x27;s much harder for someone to deny benchmarks attached to a proposed change. It&amp;#x27;s too easy for reviewers to knock out functionality.&lt;p&gt;Design documents turn every feature into a half-assed, lowest-common-denominator risk-minimized barely-adequate shell of itself.&lt;p&gt;The real reason everyone at Google writes design documents is that promotion committees demand documents as &amp;quot;evidence of complexity&amp;quot;. No design document, no impact. No impact, no promotion.&lt;p&gt;Code is just code. Bad changes can be backed out. It&amp;#x27;s much better to move fast and iterate quickly than to create an illusion of care and add friction to every aspect of the development process. Up-front design of software just does not work. If it did, waterfall project planning would be successful.&lt;p&gt;These questions you highlight --- Why are you making this change? What impact will it have? --- can be asked during review of actual code. There is no need to build a speedbump, not if you trust your people.&lt;p&gt;Developers should be able to &lt;i&gt;choose&lt;/i&gt; to create design documents and solicit feedback. Most changes don&amp;#x27;t need this process. You should trust developers to know what changes require a more extensive discussion and which ones don&amp;#x27;t.&lt;p&gt;A culture that requires permissions and signoffs before work can begin is a culture that leaves products stagnant for years.</text></item><item><author>yegle</author><text>At Google, if you want to implement new features (or large refactoring), you&amp;#x27;ll need to write a design doc. In which, you should answer questions your reviewers might ask (common questions like: why do you want to do this, what are the alternatives, how components interactive with each other before&amp;#x2F;after your change). This is something like Python&amp;#x27;s PEP: you need a proposal to convince your reviewer that you have put thought into your change.&lt;p&gt;Real world examples of these design docs can be found at &lt;a href=&quot;https:&amp;#x2F;&amp;#x2F;github.com&amp;#x2F;golang&amp;#x2F;proposal&quot; rel=&quot;nofollow&quot;&gt;https:&amp;#x2F;&amp;#x2F;github.com&amp;#x2F;golang&amp;#x2F;proposal&lt;/a&gt;</text></item></parent_chain><comment><author>skj</author><text>We write design docs at Google to communicate ideas with each other. They&amp;#x27;re useful for promo committees because effective communication between engineers is something that is prerequisite for effective engineering.&lt;p&gt;Of course a full design doc is not needed for every change. Many changes are small and straightforward. Only big things, where the team needs to discuss and understand options. Or bigger things, where directors etc need to sign off (not really design docs anymore, but same basic thing).&lt;p&gt;The fact is that, on average, design doc+code takes less time than code without design (that is, without communication). Again, only for certain kinds of changes. Things go faster because problems are found, approaches are adjusted, or unmotivated features are axed.</text></comment>