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.
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.
Requiring some basic rigour to the thinking is good though.
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.
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...
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.
Maybe it's just me, but this sounds quite heavy.
* 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.
Just let me know what you want to learn, how you hope to use it, and what you've tried in the past.
kthx
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.
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.
Its not a bluff, when the point is to weed out the ones, who aren't willing to actually do a written proposal.
One could answer, "Sure, but that will take away time from current things that need attention."