4 ms·

I use architecture docs constantly at work as a way to scale myself. I can get a decent first cut 4-8 page doc with problem summary, rationale, implementation (

I use architecture docs constantly at work as a way to scale myself. I can get a decent first cut 4-8 page doc with problem summary, rationale, implementation (usually api and some schemas), interaction diagram, alternatives considered done in a 4-6 real world hours now. This is for a 1-3 engineer month sized project. I also find I can get a 3 page one done with less details on schema and api in about 1-2 hours. I find that being able to do this allows me to scale myself a ton. I can take a discussion I had with other engineers in a design session, or my thoughts on an implementation, written up quickly. I can then take these docs and send them around and have a concrete place for everyone to start discussion. I find even if my idea is not what others are thinking, it greatly helps them articulate the delta and why. The opposite is everyone sits in a meeting and argues for their point of view in parallel while they do the design on their idea in parallel, which causes more fighting. So to me the cost of an arch doc is not very high anymore, and the effectiveness is very high. I can send that doc to 30+ people and not have to have the same 1-2 hour conversation over and over. However it took me quite a while to be able to get my thoughts onto paper that fast. I also find the 1-3 page writeups help me sell managers on spending the time on the longer doc either for me or their team. The other thing that has been great for me is that I can write up distracting ideas (I have bad shiny object syndrome), quickly, and get them to my peer manager. This means I can go back to my current work without worry about it being forgotten about. Usually I get feedback in a day or so from the manager on how good the idea is and where it fits priority wise. This allows me to innovate and implement at the same time.

shandor 8y ago
Any concrete examples you could share? This sounds like an absolutely fascinating take on the matter.
- grogenaut 8y ago
  Okay thought of an example I can give, this is one of the 1-3 page writeups. We had a new product we were rolling out a few years back. One big worry long term was a fraud potential. We were essentially paying contractors to insert content into audio. Long term on this product it could be a problem that people were defrauding us, but we didn't know for sure and we didn't know if we could do it at massive scale due to fraud risk. The product was being piloted and didn't think it'd launch for 1-2 years at scale. This was a big business worry, and the team didn't have time to look at it. At the same time google and amazon released their audio to text apis. I took a few sample audio clips, ran it through these systems and got some basic detection numbers. I ran the cost projections on it, and diagrammed a basic system diagram. I also pointed out limitations and strengths and gave a basic level of effort to implement it. I also compared it to manual verification and tossed in some stats coverage needs to detect bad actors from our data scientists. I also took my questions to our ML team and got their expert opinion. This let us a) quantify the risk and solution possibilities, b) push back worrying about the fraud as we had a likely fix at scale, c) described to everyone that basic solution so we could discuss it, d) discovered we had some experts at the company who had experience in this exact area. Sure this might be more a "research" paper or a "feasibility study" call it what you will. it's the same format as more filled out arch documents. this took me about 4 hours coding and 45 minutes to write up. Engineers were like "cool" and managers were happy to know the risk assessments and solutions and costs. Given I did the fraud math for them they were able to make a strong business case for ignoring the risk until later. some people call this removing risk, others call it resolving ambiguity. whatever, it's just digging into something and communicating effectively.
scruple 8y ago
It's very interesting to read this. I've come around to the exact same ideas, with the same perspective, and for the same reasons you've listed here. I've also had the same experience. These docs are critical for my team at this point. Without them, we'd go back to languishing for any number of weeks while we grapple to understand the larger context. All of that said, it takes me at least 2x longer to get these documents created. It's easily a 1-2 day affair for me. I'm also on a small team, with only 4 engineers, and the projects we work on tend to run 1-3 months. I wonder if this process scales to larger teams and projects.
- grogenaut 8y ago
  It used to take me that long. For more detailed docs it still does. I'm also way slower when it comes to business justification and executive team arguments but getting better. Practice makes perfect though. 5 years ago it would take me multiple months to write such a doc and I'd get bored constantly. Now I'm much faster. Some of my mentors can do these things on the fly in a meeting and drive consensus easily on stuff they have 0 context on. I also got better because I had a manager who suggested that I just start writing these things up for a few hours each week. Just like authors who say that you have to write to get better at it, and how you write essays in high school and college even for arguments you don't believe in. As for scale the process, yes it seems to. We try to review anything that's 3 months engineer time or more with a Sr. engineer from another team. Wider for larger projects. Bring in Principals when you have real quandaries. The trade off is really writing time to communication effectiveness. If you find yourself having the same slack discussion more than 2x, maybe it should be in a document.
ilaksh 8y ago
The problem is that the design you dictated at the outset isn't informed by the details that the coders are privy to. So it becomes a liability as much as it was initially an asset.
- grogenaut 8y ago
  I think you may be assuming I'm not familiar with the current application. I am. I've worked on all of them, have access to all the source code, and I'm very good at asking questions with the teams. I think you're also assuming a level of depth around these arch documents. Much of it is highly fungible discussion facilitators, not hard design requirements. Call it a 60% architecture. If it's systems I don't know anything about, then I'm going to limit myself to architecture reviews. And the engineers on the team will do the same deal. I'm a higher level engineers so I do cross team reviews a lot. But Them being able to write up fast arch docs helps them with their team and with larger reviews. For existing systems with totally new features it doesn't acutally matter that much what the existing system looks like. All of our applications are mainly micro-services with the same rpc mechanism, using one of just a few data stores, all running in the cloud. There's really not that many different things people can be doing. At the end of the day it's an RPC service that does some business logic and stuffs it in a database, or fetches it, with maybe some asynchronous processing or a workflow engine, and maybe a cache. I may also misunderstand your statement.
flarg 8y ago
This works for me. Deferring dev work to the latest possible moment is more efficient when faced with mediocre POs and devs (in most traditional enterprises); wireframes, models and documents that you can 'test' with customers.

shandor 8y ago

Any concrete examples you could share? This sounds like an absolutely fascinating take on the matter.

grogenaut 8y ago
Okay thought of an example I can give, this is one of the 1-3 page writeups. We had a new product we were rolling out a few years back. One big worry long term was a fraud potential. We were essentially paying contractors to insert content into audio. Long term on this product it could be a problem that people were defrauding us, but we didn't know for sure and we didn't know if we could do it at massive scale due to fraud risk. The product was being piloted and didn't think it'd launch for 1-2 years at scale. This was a big business worry, and the team didn't have time to look at it. At the same time google and amazon released their audio to text apis. I took a few sample audio clips, ran it through these systems and got some basic detection numbers. I ran the cost projections on it, and diagrammed a basic system diagram. I also pointed out limitations and strengths and gave a basic level of effort to implement it. I also compared it to manual verification and tossed in some stats coverage needs to detect bad actors from our data scientists. I also took my questions to our ML team and got their expert opinion. This let us a) quantify the risk and solution possibilities, b) push back worrying about the fraud as we had a likely fix at scale, c) described to everyone that basic solution so we could discuss it, d) discovered we had some experts at the company who had experience in this exact area. Sure this might be more a "research" paper or a "feasibility study" call it what you will. it's the same format as more filled out arch documents. this took me about 4 hours coding and 45 minutes to write up. Engineers were like "cool" and managers were happy to know the risk assessments and solutions and costs. Given I did the fraud math for them they were able to make a strong business case for ignoring the risk until later. some people call this removing risk, others call it resolving ambiguity. whatever, it's just digging into something and communicating effectively.

scruple 8y ago

It's very interesting to read this. I've come around to the exact same ideas, with the same perspective, and for the same reasons you've listed here. I've also had the same experience. These docs are critical for my team at this point. Without them, we'd go back to languishing for any number of weeks while we grapple to understand the larger context. All of that said, it takes me at least 2x longer to get these documents created. It's easily a 1-2 day affair for me. I'm also on a small team, with only 4 engineers, and the projects we work on tend to run 1-3 months. I wonder if this process scales to larger teams and projects.

grogenaut 8y ago
It used to take me that long. For more detailed docs it still does. I'm also way slower when it comes to business justification and executive team arguments but getting better. Practice makes perfect though. 5 years ago it would take me multiple months to write such a doc and I'd get bored constantly. Now I'm much faster. Some of my mentors can do these things on the fly in a meeting and drive consensus easily on stuff they have 0 context on. I also got better because I had a manager who suggested that I just start writing these things up for a few hours each week. Just like authors who say that you have to write to get better at it, and how you write essays in high school and college even for arguments you don't believe in. As for scale the process, yes it seems to. We try to review anything that's 3 months engineer time or more with a Sr. engineer from another team. Wider for larger projects. Bring in Principals when you have real quandaries. The trade off is really writing time to communication effectiveness. If you find yourself having the same slack discussion more than 2x, maybe it should be in a document.

ilaksh 8y ago

The problem is that the design you dictated at the outset isn't informed by the details that the coders are privy to. So it becomes a liability as much as it was initially an asset.

grogenaut 8y ago
I think you may be assuming I'm not familiar with the current application. I am. I've worked on all of them, have access to all the source code, and I'm very good at asking questions with the teams. I think you're also assuming a level of depth around these arch documents. Much of it is highly fungible discussion facilitators, not hard design requirements. Call it a 60% architecture. If it's systems I don't know anything about, then I'm going to limit myself to architecture reviews. And the engineers on the team will do the same deal. I'm a higher level engineers so I do cross team reviews a lot. But Them being able to write up fast arch docs helps them with their team and with larger reviews. For existing systems with totally new features it doesn't acutally matter that much what the existing system looks like. All of our applications are mainly micro-services with the same rpc mechanism, using one of just a few data stores, all running in the cloud. There's really not that many different things people can be doing. At the end of the day it's an RPC service that does some business logic and stuffs it in a database, or fetches it, with maybe some asynchronous processing or a workflow engine, and maybe a cache. I may also misunderstand your statement.

flarg 8y ago

This works for me. Deferring dev work to the latest possible moment is more efficient when faced with mediocre POs and devs (in most traditional enterprises); wireframes, models and documents that you can 'test' with customers.