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

71–80 of 152 posts

Re: Writing a good design document

#71

Post by jimmySixDOF »

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…

It's also not intended to be frozen in place and some allowance should be made for refinement with out scope breaking (fine but falls under change control) -- the level of detail here is important so known unknowns are surfaced not solved. High Level Designs and Low Level Designs are different documents for a reason allowing for a sufficient approach to be optimized during the transition.

Re: Writing a good design document

#72

Post by bux93 »

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.

The dictionary defintion of optimal is just 'best'; the connotation that 'optimal' means not perfect, but satisfying multiple constraint, is engineering jargon. In fact, with 'optimal', people will often mean 'Pareto optimal' (a design where there is no change that would improve the solution on all dimensions/constraints).

Pareto optimality also implies that multiple designs may exist in a 'draw', where design 1 is better on dimension A, but worse on dimension B, and design 2 flips those. These designs are on a pareto front. Making the trade-offs explicit helps readers of the design document who come along later to choose a different trade-off when it later turns out that the relative importance of the dimensions involved changed.

Re: Writing a good design document

#73

Post by anal_reactor »

chartered_stack wrote: post #70

I often come across tips/pointers/exhortations about how to write good design documents. I generally agree that it's an important step: not just for clarifying your own thinking, but also for communicating effectively with others. However, these types of posts often lack are concrete examples of what a good design document actually looks like. I understand that many of these documents are proprietary and intended for…

The problem with design documents is that they require maintenance which takes more effort than it solves problems.

Re: Writing a good design document

#74

Post by teiferer »

chartered_stack wrote: post #70

I often come across tips/pointers/exhortations about how to write good design documents. I generally agree that it's an important step: not just for clarifying your own thinking, but also for communicating effectively with others. However, these types of posts often lack are concrete examples of what a good design document actually looks like. I understand that many of these documents are proprietary and intended for…

This should grow from within yourself. Read a lot of design docs and blog posts and articles and books. Which ones did you like? Which were confusing? And why was that? Was it the language complexity? Length of explanations? Diagrams? Too much / too little reasoning? Did you feel that the writer did a good job of picking you up were you were and brining it to a new state which now was enriched with their idea?

Constantly ask youself whether you liked a particular piece of writing and that will over time shape your understanding of what's good and what's not. Note that that's not entirely objectively quantifiable and people will have different tastes. That's also why it's hard to have a "good examples" archive because, just like with code, that would immediately people to start debating. But there is a certain core of properties most people can agree on.

Re: Writing a good design document

#75

Post by teiferer »

anal_reactor wrote: post #73
chartered_stack wrote: post #70

I often come across tips/pointers/exhortations about how to write good design documents. I generally agree that it's an important step: not just for clarifying your own thinking, but also for communicating effectively with others. However, these types of posts often lack are concrete examples of what a good design document actually looks like. I understand that many of these documents are proprietary and intended for…

The problem with design documents is that they require maintenance which takes more effort than it solves problems.

What kind of maintenance do you mean?

A design can evolve over time, but a design document's objective is to document what was going to be built at that time. If something changes, make a new design document. (Similar to blog posts or news articles, they also don't evolve over the years. You write a new one.)

It sounds like what you mean is system documentation, a handbook of sorts, and that's what needs maintenance. But that's different from a design doc.

Re: Writing a good design document

#76

Post by teiferer »

atomicnumber3 wrote: post #40
MOARDONGZPLZ wrote: post #15

Earlier quoted context omitted.

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

What do you want to see, then? Colorful prose? I and a few others really did save my company 10 million dollars one year. It was in EC2 spend for a hadoop cluster. I can tell you how we did it and who did what. Yes it was actual dollars we would have otherwise paid to AWS, it is not funny money calculated by looking at sticker rates and ignoring our discounts (which were large). I'm proud of this and it was one of my…

If you try to impress a technical interviewer then they will be more interested in the smart idea you had and how you implemented it rather than how much money it made.

Re: Writing a good design document

#77

Post by i_don_t_know »

chartered_stack wrote: post #70

I often come across tips/pointers/exhortations about how to write good design documents. I generally agree that it's an important step: not just for clarifying your own thinking, but also for communicating effectively with others. However, these types of posts often lack are concrete examples of what a good design document actually looks like. I understand that many of these documents are proprietary and intended for…

Somewhere in some comment antirez said he writes design documents for his projects before he writes a single line of code. You can browse his GitHub projects or google “antirez design documents” or “antirez specification”.

https://github.com/antirez

Re: Writing a good design document

#78

Post by 18172828286177 »

mtlynch wrote: post #30

> Amazon meetings start with the presenter passing out copies... of a prose document... The meeting starts with everyone sitting in silence, reading the document, and adding notes and questions in the margins with red pen. I've never worked at Amazon, but I've heard this a lot, and it always strikes me as an odd practice. Odder still is that it apparently works and everyone I hear talk about it seems to love it. You'…

> You're squandering precious meeting time by having everyone sit and read a document together. They could easily do the same thing ahead of the meeting, and you'd have much shorter meetings.

People don’t read ahead of meetings, and that results in wasting time discussing things already covered by docs.

Re: Writing a good design document

#79

Post by paffdragon »

atomicnumber3 wrote: post #40
MOARDONGZPLZ wrote: post #15

Earlier quoted context omitted.

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

What do you want to see, then? Colorful prose? I and a few others really did save my company 10 million dollars one year. It was in EC2 spend for a hadoop cluster. I can tell you how we did it and who did what. Yes it was actual dollars we would have otherwise paid to AWS, it is not funny money calculated by looking at sticker rates and ignoring our discounts (which were large). I'm proud of this and it was one of my…

It's perfectly fine. The important part is that you can explain during the interview what you did to achieve that impact and demonstrate the skills. A lot of BS ends there. I never threw out a CV because it contained too many numbers or it was too precise. Quite the opposite. I flag CVs that are too vague and use big words without facts often repeatedly but do not provide much information.
Post reply on HN