5 ms·

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

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.

mikepurvis 5y ago
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.
- rrrrrrrrrrrryan 5y ago
  > 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. Maybe it's just me, but this sounds quite heavy.
  - mikepurvis 5y ago
    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?"
- shoto_io 5y ago
  Could you share the basic outline / structure? Which points need to be addressed?
  - pie42000 5y ago
    Yeah, gimme one sec and I will draft up a white paper on drafting whitepapers
    - shoto_io 5y ago
      Good one! I promise to wait for it right here until you get back!
  - ZainRiz 5y ago
    Sure, could you just put your request in a google doc and share the link here? Just let me know what you want to learn, how you hope to use it, and what you've tried in the past. kthx
  - nanomonkey 5y ago
    [Design Doc Template] * 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
  - mavelikara 5y ago
    Not the GP, but here is an example that had influenced my thoughts on this topic: https://www.joelonsoftware.com/2005/08/17/the-project-aardvark-spec/ https://www.joelonsoftware.com/2005/08/17/the-project-aardva...

mikepurvis 5y ago

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.

rrrrrrrrrrrryan 5y ago
> 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. Maybe it's just me, but this sounds quite heavy.
- mikepurvis 5y ago
  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?"
shoto_io 5y ago
Could you share the basic outline / structure? Which points need to be addressed?
- pie42000 5y ago
  Yeah, gimme one sec and I will draft up a white paper on drafting whitepapers
  - shoto_io 5y ago
    Good one! I promise to wait for it right here until you get back!
- ZainRiz 5y ago
  Sure, could you just put your request in a google doc and share the link here? Just let me know what you want to learn, how you hope to use it, and what you've tried in the past. kthx
- nanomonkey 5y ago
  [Design Doc Template] * 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
- mavelikara 5y ago
  Not the GP, but here is an example that had influenced my thoughts on this topic: https://www.joelonsoftware.com/2005/08/17/the-project-aardvark-spec/ https://www.joelonsoftware.com/2005/08/17/the-project-aardva...