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

Writing a good design document

grantslatton.com

Post reply on HN
Print view View original

141–150 of 152 posts

Re: Writing a good design document

#141

Post by nickm12 »

barrystaes wrote: post #127
nickm12 wrote: post #64

The structure I prefer for a technical design document is like a three-layer onion.The first layer is the problem statement, goals, non-goals, and requirements, both functional and non-functional. The next layer is the functional specification, which describes precisely how the system will work from an external perspective. The third and final layer is the technical specification, which describes the internals. Each…

This + Layer one also explicitly identifies stakeholders, and describes the current (AS-IS) situation with annonated screenshots so everyone quickly sees what we are talking about. Layer two also lists alternative solutions considered and why not chosen. Layer three is developers making a few notes on chosen tech design, most important is the choice reasoning here. In all layers, add and use references. Less is more,…

Yes, agree with all of that. I don't think every design doc needs every possible section, but if readers would benefit from the background or the an enumeration of stakeholders, that belongs up front, before the design.

Re: Writing a good design document

#142

Post by nickm12 »

addcommitpush wrote: post #68
nickm12 wrote: post #62

> The goal of a design document is to convince the reader the design is optimal given the situation. This is a nitpick, but I don't think the goal of a design is to be optimal so much as sufficient . Software systems design, like any design, is about coping with constraints and tradeoffs. The design doc should clearly lay out these out and present an approach that meets the requirements and constraints with acceptabl…

Isn’t “making acceptable tradeoffs” (optimization) while “meeting requirements & constraints” (under constraints) simply optimization under constraints? I fail to see how this is about sufficient _but not optimal_ solutions.

I generally read "optimal" to mean "optimal according to some objective function". In the case of a technical design, the objective is not something you can readily formalize, because there are so many considerations.

For example, suppose you are designing a network service to meet some use case. Yes, it needs to meet the use case, but there are other things you care about like simplicity of the code, latency, cost to operate the service, and others.

For any design you propose, there might exist an alternate design that is strictly better by some criteria-maybe it works exactly the same but has much better latency characteristics. If an oracle gave you this design, you might agree it was more optimal and choose to implement it, but I don't think it means you failed if you come up with a (sub-optimal) design that solves the problem within the constraint.

Re: Writing a good design document

#143

Post by nickm12 »

nickm12 wrote: post #64

The structure I prefer for a technical design document is like a three-layer onion.The first layer is the problem statement, goals, non-goals, and requirements, both functional and non-functional. The next layer is the functional specification, which describes precisely how the system will work from an external perspective. The third and final layer is the technical specification, which describes the internals. Each…

To add a little more color, each section also has a branch of possibilities. Given a problem, there are many possible functional specs that could solve it. Given a functional spec, there are many possible implementations. The act of choosing from among these possibilities is designing and the design doc should lay out the choices made (and sometimes the choices not made) and why.

Re: Writing a good design document

#144

Post by housecarpenter »

chromatin wrote: post #117

The author makes the following assertion: Let me illustrate a common code organization issue some programmers run into on their first day. The novice writes terminal.print("Hello world") Then they decide they want to make the text red, so they edit their program to terminal.print("Hello world") terminal.setPrintColor("red") And then they're confused that it didn't come out red. They haven't internalized that the firs…

What do you find surprising---the fact that it doesn't come out red, or the fact that people are confused by this behaviour?

Re: Writing a good design document

#145

Post by kevincox »

nickm12 wrote: post #62

> The goal of a design document is to convince the reader the design is optimal given the situation. This is a nitpick, but I don't think the goal of a design is to be optimal so much as sufficient . Software systems design, like any design, is about coping with constraints and tradeoffs. The design doc should clearly lay out these out and present an approach that meets the requirements and constraints with acceptabl…

"Optimal" in this context includes time, effort and cost. So the design isn't perfect irrespective of these things, but it is optimal in terms of balancing the effectiveness of the solution with the effort put in.

Re: Writing a good design document

#146

Post by pertymcpert »

SatvikBeri wrote: post #49
pertymcpert wrote: post #45

Earlier quoted context omitted.

You can complain all you want on here but it's not going to change the fact that most readers including myself just glaze over them. Because as you say most are just bullshit. So keep doing it if you don't actually care. If you do, maybe try to think of a different way to communicate it that sets you apart.

I generally like it when resumes do this, and so do most people I know. I'd be interested to see surveys, I don't think it's anywhere close to universal. That said, I'm typically focused on very measurable domains (e.g. making code faster.)

I've read so many resumes over the last few years that I'm just completely overwhelmed by the practice. In fact I now judge resumes unfavorably if they use it more than very sparely.

The best resumes I read (and the strongest candidates) were ones which were very confident in their skills and experience. They showed a bit of personality (as much as you can).

Re: Writing a good design document

#147

Post by newAccount2025 »

mtlynch wrote: post #121
newAccount2025 wrote: post #120

Earlier quoted context omitted.

> Meetings are for low-latency collaboration, not information transfer. Ok, but without a doc, collaboration in a meeting can become inefficient in many ways. Folks can talk past each other, bouncing between unclear options and losing clarity on what they are even debating. Only one person can talk at a time, so folks are sitting and waiting for their turn, etc.; Strong personalities can dominate and filibuster. Writ…

I'm arguing for reading the doc ahead of time, identifying topics about the doc to discuss, then coming to the meeting with a specific agenda. > Ok, but without a doc, collaboration in a meeting can become inefficient in many ways. Folks can talk past each other, bouncing between unclear options and losing clarity on what they are even debating. Only one person can talk at a time, so folks are sitting and waiting for…

> I don't understand. These are just problems with meetings in general no matter what you do in advance. What are you arguing for?

That by simply requiring a doc, you have forced the person who called the meeting to think about what they want to achieve, and to prepare their thoughts ahead of time. This makes the agenda clear to everyone and helps to guide the discussion.

> It means that letting someone else manage your time is more efficient than managing your own time.

If we are reading the doc together in the meeting, I only need to accept/decline the meeting and I am good.

If I am expected to pre-read, I have to actively do something to schedule that pre-read time. And the doc has to be ready whenever I decide to read it. Multiply that by 10+ meetings a week for a busy manager, and you have a lot of mundane scheduling work to keep straight.

> If I need 5 minutes to read a document, how is it helpful for someone to force me to sit for 10 minutes to read it at a specific time?

I’ve not found that to be a problem in practice. I can use extra time to think and prioritize my feedback, or catch up on Slack, etc.

Re: Writing a good design document

#148

Post by methods21 »

MOARDONGZPLZ wrote: post #15
apwell23 wrote: post #9

Earlier quoted context omitted.

> Replace adjectives with data I think this idea got so pervasive all throughout tech that all the resumes that i now get are filled with so many numbers that i don't even know what to make of them.

If I get one more resume from a “seasoned professional” who has “decreased X by N%” I am going to close hiring, quit tech, and go be a hermit. N.B. I received such a resume while typing this comment and am absconding to Outer Mongolia as I type

As a hiring manager / lead for technical positions, this is fine, and often proposed by the 'resume experts'. Where I get incensed is these statements where the original design/architecture that this individual was responsible for was the problem, and they are just bringing something back to baseline where it should have started. I see this ALL THE TIME. And this is with grace towards changing requirements etc. And not just on resumes, I see this on internal corp. accomplishments, and typically the higher the level the more the savings and more the unnecessary waste was to start. For example, CFO once claimed like $20mm in savings because he decommed a financial module that they bought and NEVER used and NEVER needed - this guy crushed is bonus this year.

Re: Writing a good design document

#149

Post by tremon »

nickm12 wrote: post #64

The structure I prefer for a technical design document is like a three-layer onion.The first layer is the problem statement, goals, non-goals, and requirements, both functional and non-functional. The next layer is the functional specification, which describes precisely how the system will work from an external perspective. The third and final layer is the technical specification, which describes the internals. Each…

I usually work on infrastructure as code, and I usually swap out the third layer of the design for the first layer of the implementation. You need a fully-specced functional design and a high-level technical design, but I've found that in many cases the technical implementation details can change as the project is developed, and that means either the low-level technical design and the implementation go out of sync, or there a heavy bureaucratic process in place to prevent that -- but the natural solution is to have the low-level design and the high-level implementation to live in the same place.

That still requires the rest of your process, and perhaps even places more emphasis on those documents. The infrastructure implementation needs to follow from the high-level technical design which needs to follow from the functional specification. Because as you say, the implementation needs to be reviewed against a specification. What are you reviewing if the spec is incomplete?

Re: Writing a good design document

#150

Post by gerdesj »

farkin88 wrote: post #27
gerdesj wrote: post #24

Earlier quoted context omitted.

I'm going to have to read that MF.com link fully and properly but I can't help but notice this: "That’s it. That’s the Advice Process in its entirety." (speak to everyone involved). Presumably anyone with the term Managing as a prefix in their job title is expected to glaze over at roughly this point. Then we get to the meat: "The four supporting Elements". So I try to find out about ADRs: I follow the first link: ht…

There are so many external links, it's easy to get lost in this article. Look under content for the section titled "1. A Thinking and Recording Tool: Decision Records." It's under "The Four Supporting Elements." Here's a direct link if it's easier https://martinfowler.com/articles/scaling-architecture-conve... (Just search on that page for "The Four Supporting Elements) There Harmel-Law defines ADRs as "lightweight d…

Thank you for the links. Sorry for the delay.

I do like to wrap up ... eventually! 8)

Post reply on HN