Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

How to write an effective software design document

refactoringenglish.com

Post reply on HN
Print view View original

111–120 of 132 posts

Re: How to write an effective software design document

#111

Post by mtlynch »

CurleighBraces wrote: post #101
mtlynch wrote: post #84

Earlier quoted context omitted.

Thanks for reading! What you're describing sounds like toxic team dynamics rather than something specific to design docs. Do you work effectively with your teammates outside of design docs, or is there similar tension/hostility everywhere? What you're describing sounds like the design process working as intended (modulo the finger-pointing). The design doc should be unambiguous, and the implementation should match it…

Thanks for taking the time to reply, please take my response as earnest attempts to better myself :) So, I think I didn't elaborate on the process enough to get the answers I was looking for. Here's what happened. 1. I would uncover a requirement from the business 2. The conceptual design would be written, high level understanding of the feature etc that was trying to be written 3. Conceptual design would be signed o…

It's hard to say without knowing what things are like at the company/team you work for, but I can say the things you're describing sound unusual to me.

Most significantly, it's strange for the person writing the design doc not to be the person implementing the code. This is asking for trouble because there's a principal-agent problem[0], and also there's bound to be signal lost in the handoff between designer and implementer. It's not so unusual for the design doc author to work with a team on implementation, but they'd still be actively involved in implementation, which sounds different from what you're describing.

I've also never heard of this separation between a conceptual design doc and a logical design doc. I've been on teams where the product manager writes a UX-focused spec, and then the dev writes a technical-focused spec, but I've never heard of a conceptual vs. logical spec.

Does the org have a strong engineering culture in other ways? Like automated tests, automated deploys, automated monitoring/alerting, useful code reviews? Because the easiest answer is that you're in an org with poor software engineering practices, or at least weak documentation culture, and the design review process you're experiencing is there for historical or political reasons rather than engineering reasons.

[0] https://en.wikipedia.org/wiki/Principal%E2%80%93agent_proble...

Re: How to write an effective software design document

#112

Post by pinter69 »

mtlynch wrote: post #27
bob1029 wrote: post #10

I've never experienced a situation where a software design document meaningfully improved the overall process. At best, it helps to keep the business in sync at the expense of a much longer delivery timetable. Even high level software delivery contracts never seem to stay on rails for very long. It is often faster to just build the damn thing and see where it lands. Software is not like a nuclear power plant or offsh…

OP here! I'll admit a lot of bias because I think design docs are extremely useful, but I find that when people hate design docs, it's almost always for one of two reasons: 1. The developer has worked on teams where design docs are viewed as a pointless ritual, so authors treat them as a pointless requirement and write bad docs and their teammates view them as pointless so they don't bother giving useful feedback, re…

Num. 2 especially relatable. A good mark of high quality professional is if he presents his plan before execution to hear feedback and comments - even if they are totally against his original idea, and he can then take this feedback and incorporate effectively in a re-design.

Re: How to write an effective software design document

#113

Post by CurleighBraces »

mtlynch wrote: post #111
CurleighBraces wrote: post #101

Earlier quoted context omitted.

Thanks for taking the time to reply, please take my response as earnest attempts to better myself :) So, I think I didn't elaborate on the process enough to get the answers I was looking for. Here's what happened. 1. I would uncover a requirement from the business 2. The conceptual design would be written, high level understanding of the feature etc that was trying to be written 3. Conceptual design would be signed o…

It's hard to say without knowing what things are like at the company/team you work for, but I can say the things you're describing sound unusual to me. Most significantly, it's strange for the person writing the design doc not to be the person implementing the code. This is asking for trouble because there's a principal-agent problem[0], and also there's bound to be signal lost in the handoff between designer and imp…

Well, there's a fascinating insight, most orgs I've ever worked for have had the documentation produced by someone else and them implemented by the developer.

For instance the enterprise architect/solutions architect ( or whatever job title is fashionable at the time ) would write the document and then send it over to the development team and obviously that wouldn't work.

I actually adopted the conceptual/logical design from two ex Hewlett Packard engineers/architects who introduced the idea to me, probably some twenty years ago now!

Yep we're strong in many other ways, but finding the transition to AI challenging :)

Reviews have somewhat turned into, I send you the output from my AI agent of choice, and you tell your AI agent of choice to fix it :)

Thanks again for the time taken to reply :) It is appreciated.

Re: How to write an effective software design document

#114

Post by Fripplebubby »

mtlynch wrote: post #102
luc_ wrote: post #96

Earlier quoted context omitted.

Why do you need to review design decisions with a team anymore? I get the impression that Fable, when well directed, is better than maybe 80% of SWEs. Maybe more. [edit: Yes, I'm maybe baiting other users, but I want to know your honest opinions on this.]

I find that LLMs are still worse than humans at limiting complexity, which is one of the most important outcomes of a design review. If I tell a senior SWE that I'm creating a Discourse-like discussion forum, and I want users to have three options for selecting an avatar: (1) import from Gravatar, (2) upload a JPG or SVG or PNG or GIF, or (3) let the user draw their avatar on a canvas, the LLM will happily go and des…

I do agree with you put I would push a little further - is it that complexity itself is the enemy? Or is it that the secondary outcomes of complexity (bugs, more effort to make changes, confusing code) are the enemy? If it is the secondary outcomes that are the enemy, and AI actually effectively allows you to mitigate those outcomes (debatable! I debate this with myself all the time!), then maybe we should embrace the complexity (or the agent should on our behalf)

Re: How to write an effective software design document

#115

Post by Linux-Fan »

vjvjvjvjghv wrote: post #49

The real question is "How to keep a software design document up-to-date". I have never seen this done in an efficient way. The first version is ok and over time it deviates more and more from reality. So far my best experience has been to feed the whole thing into AI and get an overview of the project. That together with a few quick bullet points about the overall purpose of the system is pretty workable.

Don't know about efficient, but there is at least two ways which seem to work OK-ish (although not all that efficient, I gahter):

* Do regular certifications. Before certification, check if the document is up to date. If not, update it.

* Share the documents to answer teammates' questions. Like with a WIKI it may turn out that the important stuff is actually missing/undocumented/outdated. This is then a good opportunity to fix the document.

Re: How to write an effective software design document

#116

Post by vjvjvjvjghv »

Linux-Fan wrote: post #115
vjvjvjvjghv wrote: post #49

The real question is "How to keep a software design document up-to-date". I have never seen this done in an efficient way. The first version is ok and over time it deviates more and more from reality. So far my best experience has been to feed the whole thing into AI and get an overview of the project. That together with a few quick bullet points about the overall purpose of the system is pretty workable.

Don't know about efficient, but there is at least two ways which seem to work OK-ish (although not all that efficient, I gahter): * Do regular certifications. Before certification, check if the document is up to date. If not, update it. * Share the documents to answer teammates' questions. Like with a WIKI it may turn out that the important stuff is actually missing/undocumented/outdated. This is then a good opportun…

I used to work in medical devices where it's all about documentation and even there nobody took the time or had time allocated by management to work on documentation. And most people aren't good at writing so the documents were terrible.

Re: How to write an effective software design document

#118

Post by jb3689 »

I like this as reference. I haven't seen a design doc properly used for implementation in a long time. More often design docs are there to facilitate collaboration - here's the basis of conversation topics that are interesting; these are the things that matter most and here's the foundation for discussion so we can get aligned. It's all too easy for a team to ignore or TL;DR a design doc which goes on and on about things that don't matter, and that can become a problem for an architect trying to implementation which winds up going off the rails because no one actually read the doc.

Re: How to write an effective software design document

#119

Post by suttontom »

bob1029 wrote: post #10

I've never experienced a situation where a software design document meaningfully improved the overall process. At best, it helps to keep the business in sync at the expense of a much longer delivery timetable. Even high level software delivery contracts never seem to stay on rails for very long. It is often faster to just build the damn thing and see where it lands. Software is not like a nuclear power plant or offsh…

Have you never built a large piece of software that had tradeoffs? What if your teammate just goes immediately into implementation with an AI and the AI decides to use library Foo which is disallowed for certain customers and API Bar which uses a legacy IAM platform that your company is in the process of moving away from? What if there are privacy, security, or legal requirements? It's more important than ever to discuss these things with humans who know the system because an agent will blindly go off and find something that someone once made work and will use it as evidence for why that's the way things should be done.

I've written bad/poorly designed code and made decisions I regret and have had coworkers use that bad code to defend their design choices because the agent said it was the best available option.

Design documents also let the engineering team who will be reviewing your code get a high level understanding of all the pieces you're sending them. If you've ever worked at a large company or codebase it's insane to say these docs aren't helpful.

Re: How to write an effective software design document

#120

Post by jmaw »

kbruner wrote: post #61

I've found the design doc itself is relatively useless once it has been created, but that the act of creating the design doc is an indispensable part of the process. Spending time and getting your thoughts organized before diving into the team, the management and the editor makes a huge difference.

I think the design doc still has some value after it has been created. For me it almost acts like a checklist of things to be completed, and it's nice to have it in one place in bite-sized bits. My design docs will also have links to external resources and it's nice to have them in one place so I don't have to track them down later.

But I 100% agree that the majority of the value is gained in the writing of the design doc, and the decisions/tradeoffs that have to be thought through during that process. Which is why I strongly push back against suggestions of using AI to write design docs. Since delegating the writing to AI causes over half the value of the design doc to be lost.

Post reply on HN