I've actually had this happen, so I pretty much wrote a white paper (charging company time and delegating time from dedicated efforts by way of the name of the person who requested it).
I sent it, then continually followed up on the status of the points made. Some changes ultimately did get integrated because of it, I think calling the bluff forced someone to actively read, think, and respond to it, even if it wasn't leadership, they had someone else spot check and agree/disagree on points.
There’s something to be said for corporate cultures that require written memos describing each new proposal. Forcing people to “actively read, think, and respond” is a great way to increase the likelihood that the best ideas bubble up to the top.
> Forcing people to “actively read, think, and respond” is a great way to increase the likelihood that the best ideas bubble up to the top.
I think that it requires acknowledgment that there are two sides to such issues; as someone who is on the side that typically ends up having to handle the majority of the busy work to get many proposal through in my company I absolutely want the proposer to make the effort to figure out the stakeholders/costs/challenges for their project as well as answers. I'm willing to __fill in gaps__, but I don't really want to be having to do the basic legwork for someone else's project.
I don't mean to sound like I want to stifle inconvenient creativity; it's certainly not the case, and when someone has really taken the time to make some new tooling/project with benefits and acknowledges the costs involved, I'm more than happy to champion such projects.
But when someone just has a desire (or disparagingly, a whim) to change stuff up because it simplifies their workflow and they expect someone else to handle all of the communication of their project without even giving me the courtesy of doing such research, I cannot deny I approach such proposals negatively as I feel a bit used and I think that the expectation is "I want this, make it happen", which is not my job.
Similarly, I find myself encountering persons who expect that I and the rest of the company will magically intuit the importance of very niche projects without being willing to take the time to simply explain the pain point they wish to address. I'm not even talking about deep technical details here, but simple things like:
"We spend N amount of time on task X"
"I have an automation workflow that will require Y hours to implement, but N is reduced by Z [time value]"
Instead, the presentation is "I want to implement this automation workflow; what do you mean explain the value? Can't you see it? Why are we so caught up in corporate bureaucracy?"
I'm all for reducing N as much as possible, but if I myself can't explain why spending Y is vastly cheaper than N, I have no confidence in my ability to convince others that the cost of Y is worth it.
I've truly been on both sides, and it is some work to justify a change, sure. Formal proposal documents are a bit much for my taste, but whether we like it or not, C-Levels aren't going to read your code and they definitely aren't going to read a 2000+ word stream-of-consciousness email describing the project in an unstructured way (much less any git readme.md files). The impetus is on the person proposing the change to at least make an effort to convey the reason for the change to the relevant stakeholders.
It's also a surefire way to stall an idea out in paper form that by the time it comes to implementation, people have gotten distracted by other urgent work and the idea never comes to fruition.
Since time can only be spent once, you are essentially picking between a quick&dirty prototype and a nice document.
The document invites a bikeshedding session and consumes reviewer time, the prototype often allows you to immediately see whether the idea is worth pursuing, it may directly deliver a part of the benefit of the completed solution, and most importantly, it'll show the actual weaknesses in the design and the real constraints you have to deal with in a way that a theoretical review can't.
Is there a difference between white paper and design doc? My impression is that a white paper is more academic, and so I'm not sure what it ends up looking like.
At one of my jobs, we wrote design docs for most major changes (we had a checklist for deciding if the doc was necessary at all). It was ultimately quite helpful because documentation about most important changes existed, even if the dev didn't write any documentation in code. The technical designs also had a template, so it was a fairly easy path for a developer to know what questions to answer or not in their doc.
I have seen google design docs at google, most are trash. Most design docs everywhere are trash. The confuse more than they explain. I don't care if the idea is good, if the design doc stinks, it will kill a good idea.
Effectively communicating a complex idea is a skill that's orthogonal to coming up with good ideas.
I advise other engineers, especially those early in their careers, to actively develop and hone their communication skills. It deserves far more focus than most people seem to give it.
This is par the course at Amazon and, honestly, I think it's pretty great.
We all tend to get a lot of ill-thought out pet ideas about what needs to happen in a project. Even a tiny informal doc listing out what problems you're actually trying to solve is a massive boon for communication.
I agree. I'm a big fan of the lightweight design doc— what's the background, what are the motivations, what's the proposal, what are the alternatives and why aren't we doing them, what are the implications and potential downsides, does the proposal change anything about our exposures as far as security, privacy, etc.
I like the discipline of writing these out for myself, I like reviewing them, and I like being able to look back on them for my own past projects as a way to quickly warm my mental cache.
> the lightweight design doc— what's the background, what are the motivations, what's the proposal, what are the alternatives and why aren't we doing them, what are the implications and potential downsides, does the proposal change anything about our exposures as far as security, privacy, etc.
I think it's as heavy as you want it to be— not every point on there requires a whole treatise, but each is an opportunity to be like "is there information here that I have which might be useful to my colleagues or my future self?"
I don't suggest doing this as a passive-aggressive attack, but I use a variant when presenting to a group that includes the "always negative" person. I suggest they do some work investigating and sharing alternatives to the things that "won't work" and they miraculously start focusing on viable solutions.
I do this all the time, sometimes even something as simple as asking the user to write up the request in an email is enough for them to go away forever. It's a simple way to check if the requestor is invested in the request, or just trying to slide something from their to-do list to yours with zero effort...
Yeah, it's good for these kinds of discussions when it's a universal requirement, or when the white paper concerns will actually be addressed before confirming a design. I do get suspicious when it comes up for the first time when it's something someone doesn't want to hear, or when the discussion continues on like it's obviously untrue in the meantime.
Amazon is like this, and it's part of why I think I never worked out well. Too much process. Compounding the pain was the fact that my instinct would always be to whip up a proof-of-concept demo instead, for the next meeting.
Management hated that, and to this day I don't get why. I recognize the need for things to be reviewed by others, and we all can lose scope of what's important sometimes. I'm no exception. However, for things that are purely technical/scientific arguments, what's gained by me having to use the Official Template (tm) to propose an idea, and spending days messing with words and bullet points, rather than a demo that you can see with your own eyes?
It also struck me as quite hypocritical. On the one hand, professing to have a "bias for action", then on the other hand harshing on people for preferring action over another TPS reports.
See also: CIA memo "How to Infiltrate an Organization and Make it Dysfunctional" grin
It’s all about communication. I think of a POC as way to communicate what it is that needs to be created. I think a document is another way of communicating what needs to be done. Mandating one or the other seems like a fools errand to me since each one has strengths and weaknesses.
Frankly having been that manager, the demo shows what you’ve done. It didn’t lay out how to get the whole project there.
The documents are hard specifically because not you have to consider alternatives, or the feasibility of executing. What security concerns did I cover? How much time do I need to spend convincing team y to add this feature?
The demo is always the easy 50%, and never the hard parts that cause you to spend two years building alignment and executing.
As always, nothing in the world can take the place of prudential judgement. When proposals should be written up to avoid senseless action and short-term thinking, and when they should be avoided because they would constitute bikeshedding or overthinking or whatever, is a matter of prudence and competence gained through experience. There is no algorithm that will allow you to mindlessly come to the correct decision.
A demo is no substitute for a written proposal and vice versa. The first is empirical, the latter is analytical and deliberative. Each has its proper place. Really, the demo is a way to corroborate the proposal, so it's a question of how rigorous the proposal needs to be. Some minor tweak might only require a quick discussion while a deep change will require deeper consideration.
If your argument is any good, then all this whitepaper would do is make a better case. Asking for a whitepaper is not a bad thing for ideas that require some careful consideration. They're overkill for trivialities that can be fully decided here-and-now and or for things that don't really matter.
Too often have I seen developers running in circles chasing ideas that could have been ruled out with a little forethought and analysis. They'll respond superficially to some idea that tickles their fancy, waste a bunch of time implementing it only to either realize that it's a bad idea, that it has serious drawbacks, or better yet, leave everyone with a dreadful piece of garbage to maintain.
It also lives on in the work of BeOS engineers who infiltrated Apple: Tracker -> Finder, BeFS -> Matador, Spotlight, MediaKit -> Final Cut Pro, various media libraries and more. Possibly a lot of the C++ work we did at Apple after leaving Be has been purged, but some still lives!!!
I'm pretty sure I saw some DNA from Gobe Productive, the Be answer to AppleWorks, lurking in iWorks. (Which is kind of recursive, since Gobe was created by most of the original AppleWorks team after ClarisWorks' demise, IIRC, who were then hired by Apple after Gobe's demise...)
> BeFS -> Matador
Was Matador a code name for APFS, or is this something else entirely?
Wow ClarisWorks. That’s a throw back. That was around the time of Quark Express I think?
Pops was a graphic designer so got to grow up with that evolution and consolidation of the various programs that all eventually were either subsumed or put out of business by Adobe (and I guess MS).
That sounds right. AppleWorks became ClarisWorks, then (I think!) became AppleWorks again for a while. Meanwhile, the folks at Claris left to create Gobe, and improved on the idea with Gobe Productive. Then, much later, they came back to Apple and worked on iWorks (Numbers, Keynote, Pages) -- which aren't the same as ClarisWorks or Productive, both of which were standalone monolithic apps (if I'm remembering right), but there's definitely a visible lineage. The iWorks apps are better than they're often given credit for, as was Productive.
There are still competing programs existing in the margins -- iWorks is obviously still around, and there are some other word processing apps hanging in: Nisus Writer for the Mac and Nota Bene for Windows have both managed to persist since the 1980s, although they're both pretty different programs than they were then. And Adobe definitely has competitors in indie shareware these days, like the Affinity applications. (And of course there's open source competitors like LibreOffice, GIMP, etc.)
>It doesn't. That's just a "template" file, which I use search and replace in order to generate the three monomorphized go files.
>If you look closely, those aren't angle brackets, they're characters from the Canadian Aboriginal Syllabics block, which are allowed in Go identifiers. From Go's perspective, that's just one long identifier.
At an Internet-major co in my country, my VP Engineering told me "We don't run stuff downloaded from the internet around here" - I was proposing to trial a Solr/Lucene based search backend as a replacement for the awful MySQL based hacked-together search they then had.
I wanted to ask him if he got his copies of Apache/Mysql/php/Redhat on government stamp paper. Instead, I quit two weeks later.
Maybe they just installed it from redhat cd-roms or dvd-roms and never updated their systems, and considered it "trustworthy" because it came on physical media from the vendor. Have seen that more than once.
On a more serious note, when the VP of engineering or CTO or somebody similar takes such a dreadfully ignorant approach, it's a very good indicator that something is more fundamentally wrong and to jump ship.
Such a person should be at least capable of understanding the modern concept of how something like a .deb file is authenticated based on its hash from the public gpg keys for the debian package server in question, or the equivalent thereof for redhat/centos.
I worked at a place where I couldn't download Linux and install it, I had to buy it from somewhere. I bought whatever the latest version of Redhat was, and then I downloaded the latest from their site (since I'd have to update anyway), and nobody questioned it even though I installed it way before the software actually got delivered.
On the other hand, I bought the most expensive version I could ($139 vs $49 or $79, just to throw some money Redhat's way)
A guy being interviewed as a CTO was trying to argue an entire rewrite was needed to move from Postgres to MongoDB (for tabular data). His argument was, and I quote: ‘I’m right, and I don’t need to explain myself to you.’. That was to the non technical cofounder. To myself he just said, ‘I don’t mean any disrespect, but you don’t know how to scale ’. This was literally for a basic crud application with 0.1% usage on a RDS micro instance.
> I’m right, and I don’t need to explain myself to you.
Having "I'm an asshole" tattooed on his forehead would have been less noticeable. We should all be so lucky that interviewees give such clear cut signals.
That one's evergreen, in Web Dev. Whatever pattern's current now was a laughable newb mistake that'd get you branded too dumb to do web dev, a few years ago. In another couple years, it'll be "common knowledge" that the current thing was always terrible, and the new thing, which is now considered extremely dumb and nothing a pro would ever do, will be in vogue.
For instance, going from misusing XML as a domain-specific language to misusing YAML as a domain-specific language while patting yourself on the back about how you got to move away from nasty XML.
I used to do that with a friend at my first job. We'd argue for hours until we found a good solution. The joke, of course, is that everything before then was stupid.
Of course, this assumes goodwill and friendship between the arguing parties. There is nothing wrong with losing an argument when a better solution exists.
> I like your idea. Why don't you write up a white paper and we'll review it at the next staff meeting
I once fell in this trap. Almost two months researching competitors to a solution I had proposed because a coworker proposed something else. At the meeting to present both solutions he was fiddling on his phone and when asked his thoughts after my presentation, just replied "yeah, it's fine".
It was a pretty high impact high risk architectural decision. Apparently only I took it seriously enough and the other guy made a fuss about it initially but didn't even care about the outcome. Unfortunately, management became very unsure of everything and thus the wasted time proving my solution would be acceptable. Anyway, I learned a lot so it's all good.
I have been through this. Learn from my experience. If someone else has an alternative proposal, ask THEM to write it down for you to consider.
No one is allowed to propose something without first proving that they did the homework or that there is a need to even consider what they are thinking.
I don't get it. Some items on that list can be legitimate, non-technical objections, like 3, 5, 7, 30, 31, 33, 56, 58. Others can be legitimate, technical objections, like 1, 6, 19, 46.
That's terrible advice if the objection is of legal nature, for example, or when human safety is at stake. Also, you typically don't have unlimited resources, so "you just have to try something" isn't a good justification if there valid objections against its feasibility.
136 comments
[ 2.7 ms ] story [ 201 ms ] threadI sent it, then continually followed up on the status of the points made. Some changes ultimately did get integrated because of it, I think calling the bluff forced someone to actively read, think, and respond to it, even if it wasn't leadership, they had someone else spot check and agree/disagree on points.
I think that it requires acknowledgment that there are two sides to such issues; as someone who is on the side that typically ends up having to handle the majority of the busy work to get many proposal through in my company I absolutely want the proposer to make the effort to figure out the stakeholders/costs/challenges for their project as well as answers. I'm willing to __fill in gaps__, but I don't really want to be having to do the basic legwork for someone else's project.
I don't mean to sound like I want to stifle inconvenient creativity; it's certainly not the case, and when someone has really taken the time to make some new tooling/project with benefits and acknowledges the costs involved, I'm more than happy to champion such projects.
But when someone just has a desire (or disparagingly, a whim) to change stuff up because it simplifies their workflow and they expect someone else to handle all of the communication of their project without even giving me the courtesy of doing such research, I cannot deny I approach such proposals negatively as I feel a bit used and I think that the expectation is "I want this, make it happen", which is not my job.
Similarly, I find myself encountering persons who expect that I and the rest of the company will magically intuit the importance of very niche projects without being willing to take the time to simply explain the pain point they wish to address. I'm not even talking about deep technical details here, but simple things like:
"We spend N amount of time on task X"
"I have an automation workflow that will require Y hours to implement, but N is reduced by Z [time value]"
Instead, the presentation is "I want to implement this automation workflow; what do you mean explain the value? Can't you see it? Why are we so caught up in corporate bureaucracy?"
I'm all for reducing N as much as possible, but if I myself can't explain why spending Y is vastly cheaper than N, I have no confidence in my ability to convince others that the cost of Y is worth it.
I've truly been on both sides, and it is some work to justify a change, sure. Formal proposal documents are a bit much for my taste, but whether we like it or not, C-Levels aren't going to read your code and they definitely aren't going to read a 2000+ word stream-of-consciousness email describing the project in an unstructured way (much less any git readme.md files). The impetus is on the person proposing the change to at least make an effort to convey the reason for the change to the relevant stakeholders.
Requiring some basic rigour to the thinking is good though.
Since time can only be spent once, you are essentially picking between a quick&dirty prototype and a nice document.
The document invites a bikeshedding session and consumes reviewer time, the prototype often allows you to immediately see whether the idea is worth pursuing, it may directly deliver a part of the benefit of the completed solution, and most importantly, it'll show the actual weaknesses in the design and the real constraints you have to deal with in a way that a theoretical review can't.
One could answer, "Sure, but that will take away time from current things that need attention."
Its not a bluff, it is a way of weeding out the non-serious requests.
If you take the time then so will I.
Its not a bluff, when the point is to weed out the ones, who aren't willing to actually do a written proposal.
context: design docs are frequently written at G.
At one of my jobs, we wrote design docs for most major changes (we had a checklist for deciding if the doc was necessary at all). It was ultimately quite helpful because documentation about most important changes existed, even if the dev didn't write any documentation in code. The technical designs also had a template, so it was a fairly easy path for a developer to know what questions to answer or not in their doc.
Is this the same idea as a white paper?
I advise other engineers, especially those early in their careers, to actively develop and hone their communication skills. It deserves far more focus than most people seem to give it.
The appear to be an artifact of a policy, the problem they solve is 'not having a design document' and nothing more.
We all tend to get a lot of ill-thought out pet ideas about what needs to happen in a project. Even a tiny informal doc listing out what problems you're actually trying to solve is a massive boon for communication.
I like the discipline of writing these out for myself, I like reviewing them, and I like being able to look back on them for my own past projects as a way to quickly warm my mental cache.
Just let me know what you want to learn, how you hope to use it, and what you've tried in the past.
kthx
* Background
Background on the problem we’re solving.
* Design Goals
Requirements and goals of the project. This should also include numbers like traffic assumptions, usage, uptime requirements, etc.
* Other Proposals
Options that were looked at, but we evaluated that weren’t going to work
1. Option 1
2. Option 2
* Solution Summary
Summary of the solution in a paragraph or two.
* Solution Details
Details of the solution...feel free to add/remove sections that make sense, some starter ones are below.
* System diagram
Diagram of all the binaries, databases and 3rd party services that this system touches
* Wire frames
Any wireframes for the UI if this has a frontend component?
* Code
Where is the code going to go? Does this touch any common repos? Any new repos being created?
* Testing
What kind of testing is going to be done. Unit tests, regression tests, etc.
* Scaling
What aspects of traffic do we need to think about for scaling. If the traffic goes 10x, we ok? could the database grow 10x and cause issues?
* Operation details
Details that the operations team might want to know like location of binaries, monitoring to be setup, oncall, etc
* Internationalization
Do we need to think about spanish?
* Tradeoffs made
Write out the big tradeoffs made
https://web.archive.org/web/20051224054905/http://www.joelon...
If that was helpful, then please donate.
https://archive.org/donate
Maybe it's just me, but this sounds quite heavy.
I do this all the time, sometimes even something as simple as asking the user to write up the request in an email is enough for them to go away forever. It's a simple way to check if the requestor is invested in the request, or just trying to slide something from their to-do list to yours with zero effort...
Management hated that, and to this day I don't get why. I recognize the need for things to be reviewed by others, and we all can lose scope of what's important sometimes. I'm no exception. However, for things that are purely technical/scientific arguments, what's gained by me having to use the Official Template (tm) to propose an idea, and spending days messing with words and bullet points, rather than a demo that you can see with your own eyes?
It also struck me as quite hypocritical. On the one hand, professing to have a "bias for action", then on the other hand harshing on people for preferring action over another TPS reports.
See also: CIA memo "How to Infiltrate an Organization and Make it Dysfunctional" grin
There's a subtle but important thing to note here. My bet is management didn't hate that you did a POC. They hated that you DIDN'T also do a writeup.
It's not about this vs that. Meet the minimum requirements before you go doing extra.
The documents are hard specifically because not you have to consider alternatives, or the feasibility of executing. What security concerns did I cover? How much time do I need to spend convincing team y to add this feature?
The demo is always the easy 50%, and never the hard parts that cause you to spend two years building alignment and executing.
A demo is no substitute for a written proposal and vice versa. The first is empirical, the latter is analytical and deliberative. Each has its proper place. Really, the demo is a way to corroborate the proposal, so it's a question of how rigorous the proposal needs to be. Some minor tweak might only require a quick discussion while a deep change will require deeper consideration.
If your argument is any good, then all this whitepaper would do is make a better case. Asking for a whitepaper is not a bad thing for ideas that require some careful consideration. They're overkill for trivialities that can be fully decided here-and-now and or for things that don't really matter.
Too often have I seen developers running in circles chasing ideas that could have been ruled out with a little forethought and analysis. They'll respond superficially to some idea that tickles their fancy, waste a bunch of time implementing it only to either realize that it's a bad idea, that it has serious drawbacks, or better yet, leave everyone with a dreadful piece of garbage to maintain.
> They're overkill for trivialities ... and or for things that don't really matter.
I think you answered your own question.
It seems like an underhanded way to stifle technical debate.
You used to program in Pascal, didn't you?
Giving this a go on my next argument XD
I get the rest of the references, but what is a Be obsession? Also the last one is gold
Put out of business by everyone's favorite monopolist, but to some extent it lives on as Haiku: https://www.haiku-os.org/
> BeFS -> Matador
Was Matador a code name for APFS, or is this something else entirely?
Pops was a graphic designer so got to grow up with that evolution and consolidation of the various programs that all eventually were either subsumed or put out of business by Adobe (and I guess MS).
There are still competing programs existing in the margins -- iWorks is obviously still around, and there are some other word processing apps hanging in: Nisus Writer for the Mac and Nota Bene for Windows have both managed to persist since the 1980s, although they're both pretty different programs than they were then. And Adobe definitely has competitors in indie shareware these days, like the Affinity applications. (And of course there's open source competitors like LibreOffice, GIMP, etc.)
(Oh, and QuarkXpress is still around!)
[1] https://en.wikipedia.org/wiki/BeOS
2) Thank you.
Oh my god, I'm a terrible person!!
:)
Oh so this is where some people in the Go community got their main argument against generics...
>It doesn't. That's just a "template" file, which I use search and replace in order to generate the three monomorphized go files.
>If you look closely, those aren't angle brackets, they're characters from the Canadian Aboriginal Syllabics block, which are allowed in Go identifiers. From Go's perspective, that's just one long identifier.
I wanted to ask him if he got his copies of Apache/Mysql/php/Redhat on government stamp paper. Instead, I quit two weeks later.
6D Chess: set up an LLC to do this, and convince the place to buy the discs at significant markup.
Such a person should be at least capable of understanding the modern concept of how something like a .deb file is authenticated based on its hash from the public gpg keys for the debian package server in question, or the equivalent thereof for redhat/centos.
On the other hand, I bought the most expensive version I could ($139 vs $49 or $79, just to throw some money Redhat's way)
"The artifact may have dependencies and we're analyzing those now, Sir." Especially useful when you've upgraded and it all goes to hell.
Those damned artifacts will get you every time.
I would have loved to hear any technical excuse
Having "I'm an asshole" tattooed on his forehead would have been less noticeable. We should all be so lucky that interviewees give such clear cut signals.
I cackled pretty hard at this one.
I used to do that with a friend at my first job. We'd argue for hours until we found a good solution. The joke, of course, is that everything before then was stupid.
Of course, this assumes goodwill and friendship between the arguing parties. There is nothing wrong with losing an argument when a better solution exists.
I once fell in this trap. Almost two months researching competitors to a solution I had proposed because a coworker proposed something else. At the meeting to present both solutions he was fiddling on his phone and when asked his thoughts after my presentation, just replied "yeah, it's fine".
Key is to find minimum required effort.
No one is allowed to propose something without first proving that they did the homework or that there is a need to even consider what they are thinking.
Things to Say When You're Losing a Technical Argument [2001] - https://news.ycombinator.com/item?id=7982845 - July 2014 (2 comments)
Things to Say When You're Losing a Technical Argument (2001) - https://news.ycombinator.com/item?id=1440999 - June 2010 (21 comments)
But is it multi-cloud?