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

131–140 of 144 posts

Re: How to write an effective software design document

#131

Post by RaftPeople »

cryptonector wrote: post #126
RaftPeople wrote: post #107

Earlier quoted context omitted.

> I've never experienced a situation where a software design document meaningfully improved the overall process. If you don't have a document, then how do you make sure that internal team A and internal team B and internal team C and external vendor D and external vendor E all create the correct things so the entire system actually works?

At Sun we didn't use design docs for this. We used architecture docs instead. These were of the form of PSARC cases with materials such as: - interfaces lists, with attached commitment levels - interface contracts where interface commitment levels do not otherwise allow teams A, B, and C to use each other's interfaces. That's much better than design docs. The difference between architecture and design -at Sun anyway-…

I was thinking in terms of a broad usage of "design" which tends to match what you wrote about architecture.

Re: How to write an effective software design document

#132

Post by reddit_clone »

pinter69 wrote: post #112
mtlynch wrote: post #27

Earlier quoted context omitted.

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.

This does not always work.

Often, the group members presented to, do not have the required knowledge to critique the design document.

I have seen people proposing (demanding even) changes based on vague feelings and their need to be seen as contributing.

Once they say something, it is out there, now it is the poor presenter who has to refute it or accept modifications to the design.

Re: How to write an effective software design document

#133

Post by trinsic2 »

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…

I disagree. Having a design doc would have saved me some time having to rewrite certain parts of a CRM system I am working on in Obsidian[0]. Not having a plan on handling certain aspects up from can make more work.

[0]: https://www.scottrlarson.com/blog/article-crm-obsidian/

I think this is a good idea. Thanks to the author.

Re: How to write an effective software design document

#134

Post by cryptonector »

RaftPeople wrote: post #131
cryptonector wrote: post #126

Earlier quoted context omitted.

At Sun we didn't use design docs for this. We used architecture docs instead. These were of the form of PSARC cases with materials such as: - interfaces lists, with attached commitment levels - interface contracts where interface commitment levels do not otherwise allow teams A, B, and C to use each other's interfaces. That's much better than design docs. The difference between architecture and design -at Sun anyway-…

I was thinking in terms of a broad usage of "design" which tends to match what you wrote about architecture.

Often people mean "architecture" when they say "design", yeah.

Re: How to write an effective software design document

#135

Post by bigstrat2003 »

luc_ wrote: post #96
mtlynch wrote: post #71

Earlier quoted context omitted.

> The biggest thing AI enables is cheap code. Agree, but in my experience that doesn't change much about the design doc. I think it's helpful to the author to be able to say to an AI agent, "Hey, put together this quick prototype," and that informs the design doc. But if the goal is to review the design decisions with the team, I don't see how you get around the design doc. I don't want a teammate to send me 10 KLOC…

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.]

LLMs are worse than any competent programmer. Just turning them loose is a terrible idea.

Re: How to write an effective software design document

#136

Post by rendaw »

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…

So you need to believe in design documents, and if you don't like them you're probably trying to manipulate people? But have you justified design documents?

I can think of situations where design document(s) would be a clear use, and I think that would be a better way to respond.

Re: How to write an effective software design document

#137

Post by chandureddyvari »

If you’re like me and often create product specs and technical design docs for agents, I found these kind of specs(if LLM generates) mostly would be 10s of pages and you are subjected to fatigue from reading and reviewing them.

What worked for me was to ask Astra/Fable to include pseudo code in the design doc. which comes to 1-2 pages. Easy for me to skim and change the direction/approach. Rest all of the flowery language is for LLM giving context.

Re: How to write an effective software design document

#138

Post by bad_username »

fg137 wrote: post #91

> A good design doc can save you years of development time. I only have a few years of experience in this business, but I have seen numerous cases where none of this matters. Your perfectly drafted plan could easily be derailed by technical limitations, customer request or company reorg. You are better off use that planning time for something else.

> Your perfectly drafted plan could easily be derailed by technical limitations, customer request or company reorg.

These are not guaranteed to happen. But if you don't have a plan, you will be derailed very soon and practically inevitably.

Re: How to write an effective software design document

#139

Post by harrouet »

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…

I am on the design-doc team and I'd like to add the 3rd category:

3. The developer is not able to imagine how the design works because s/he has no capability for abstraction. Needs to go hands-on.

I might add that writing the doc is not the purpose, the purpose is to think it, challenge it and share it.

Re: How to write an effective software design document

#140

Post by tom-k »

barrkel wrote: post #67
AnimalMuppet wrote: post #51

Earlier quoted context omitted.

> At best, it helps to keep the business in sync at the expense of a much longer delivery timetable. If you're writing a software design document that slows down your delivery timetable, you're doing it wrong. (Or, more charitably, your business is doing it wrong.) If your design document is to keep the business in sync, you're doing it wrong. That's not what a design document is for. It's for keeping you in sync. >…

Instead of thinking through all the places in the code the AI is going to have to touch, why not kick off three parallel agents implementing the thing and finding out what they did and the tradeoffs they found? Planning is essential but it doesn't survive contact with reality. However, AI makes contact with reality cheap! Why not use it to improve designs, by writing the design after a few implementations have alread…

[flagged]
Post reply on HN