2 ms·
I agree with the issues raised by the article but disagree with the conclusion. Prose is great but the way he suggested creating an architectural doc up front
by ilaksh 8y ago
I agree with the issues raised by the article but disagree with the conclusion. Prose is great but the way he suggested creating an architectural doc up front doesnt sound like it can evolve as the trench warfare progresses.
I feel like a big part of the issue is the disconnect between management and development people in many ways. Most managers only really care about the surface level of the software. Their situation of not being able to directly control the guts and the fact that their boss only sees the surface level reinforces that.
Another issue is that management expectations are almost always unrealistic. It's the nature of software development because it is a research process where it's exponentially easier to envision the next step than it is to implement it.
My current belief is that both project managers and even executives need to be forced to look at at least some code every now and again and included in software engineering meetings routinely. That is the only way they will start to understand the scope of the work and realize that there is work under the surface.
- marvin 8y agoI think the reasoning must go one step further -- project managers and _especially_ executives need to have rich personal experience with building software. That doesn't necessarily mean that they must have spent years programming for themselves, but at the very least they should have spent a few years closely paying attention to the whole life-cycle of software projects. That way, they can appreciate the difficulties of estimating delivery timelines for an evolving scope, the nasty surprises that will invariably bite them in the ass, what technical debt means, the value of refactoring and consolidating, how something that sounds simple can be hard and the canaries that indicate a certain feature has that property, and so on. The most formidable product person I know has spent six years working closely with a team of five engineers, on a portfolio of complex products. He can often predict technical challenges before the engineers see them. He's the best tech executive we dream of in our organization, but due to the diseased nature of executive hiring at our firm, it's not very likely he'll get a job at the top.
- grogenaut 8y agoI 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 agoAny concrete examples you could share? This sounds like an absolutely fascinating take on the matter.
- grogenaut 8y agoOkay 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 agoIt'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.
- walshemj 8y agoWhy do you think that? ok its going to be some what slower and require work to identify changes to existing code.
- antaviana 8y agoWe use Confluence for the prose and JIRA for items with a life cycle. You can link very nicely from Confluence to JIRA items.
- dahdum 8y agoI think part of his views are colored by his job, where they are doing work for external customers. Prose and architectural docs up front can ease the sales process and get the customer on board. My experience with Jira was positive, it organically grew into every department. We never had to bill customers by the hour or produce burndown charts for upper management though. Though, all our larger projects did start with Confluence wikis, and each meeting would be summarized in a comment/edit, or a subpage. Similar to what he proposes I guess.