Live data from Hacker News

Writing a good design document

grantslatton.com

81–90 of 152 posts

Re: Writing a good design document

#81
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…

Yes! Non-goals are SO important.

In IT, it's all virtual, so in theory anything is possible. Setting hard limits is necessary, or else the solution space is overwhelming, and the second system effect can kill your project (even in the first system!)

In mechanical or electrical engineering, some potential goals are blatantly physically or economically impossible and do not need to be mentioned as non-goals.

Re: Writing a good design document

#82

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…

Not sure about the author, but having a few hundreds interviews under my belt (as the interviewer) some of those statements are incomplete.

Your example is complete, but if I see statements like: "decreased latency by 5%" I will ask you if are we talking about median or long tail latency. Another example would be "developed a ML model that increased revenue by X%". Here it is missing how the population is affected. If you say overall then I will ask you things like: "For which slice of the population did you see the biggest improvement with the new model? Any regression?" or "Did you run any control group".

While I might or might not care about the technicalities of your answer the important thing is that if you can't convince me that you know what you are talking about then it is as parent said, bullshit and I will stop likely paying attention to you and mind my business as I will suggest a no-hire.

If, instead, it looks like you really did those things you mentioned it is a nice ice breaker and genuine candidates seem to perform well when they get the tension out of the way by answering something they know.

PS: If I were to interview you I would ask "How" because as I mentioned it is a complete statement in my mind :)

Re: Writing a good design document

#83

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 AWS Lambda PR/FAQ was released late last year - worth a read

https://www.allthingsdistributed.com/2024/11/aws-lambda-turn...

Re: Writing a good design document

#84
Compressing your text can not be stressed enough. It makes you think „what do I like to say here“ and that is what most text I have read are missing. In my bussines there is a software called DOORS for req. writing and it’s the death of each document. Like ai slop

Re: Writing a good design document

#85

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…

Yes this is also a question that comes to my mind. Where are the design docs from the past 50 years of software development. There must be something concrete for people to study and learn from.

Re: Writing a good design document

#86

Earlier quoted context omitted.

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…

> What kind of maintenance do you mean?

> If something changes, make a new design document.

This one.

Re: Writing a good design document

#87
I'm writing this with a background of having studied and done a PhD. in software architecture in the early 2000s.

Simply put, good software documentation matters but has the annoying habit of getting out of sync with your software the second you lift your fingers from the keyboard. So, moderate the amount of time you spend on writing especially up-front documentation, like design documents, because they'll have a short shelf life and an even smaller audience. Worst case it's just you. And that's actually fine.

Use them to structure your thoughts. Shoot some versions back and forth with your colleagues to build consensus. And then archive them.

Back when I was doing my PhD. it was peak UML hype. I was interviewing people with important sounding job titles (e.g. Lead Architect) and they'd be in a private office with a prominently displayed Rational Rose box on the shelves. They'd be spending lots of time making diagrams. This job does not really exist any more.

A few years later I decided to practice instead of preach and became a software developer. Now it's a few decades later and I don't do a lot of diagrams. But I do quick Markdown documents or inline documentation. The closer to the source code, the better. I'm actually pretty good about this stuff. And it's stupidly easy to generate this stuff as well these days. Which you should do. Because it really helps others and the future you (come back in four months and you'll find that your short term memory has blanked out everything you used to know about the code).

Why no diagrams? Very simple, they are either too simplistic/trivial or way too convoluted (won't fit on a single screen/slide/document page). Anything in between is quite pointless and tedious to produce. It won't communicate anything of real value that cannot be expressed in a few quick lines of text. Which is much easier to produce. The diagram is what you whip out if you need to put some lipstick on the pig that is your design for marketing purposes. "We have stuff! Look pretty diagram! next slide...".

The other reason is that as soon as you sit down to implement the design, you'll typically refine it on the fly by deviating from it. So, it rapidly goes out of date and updating it is just not a thing that ever happens.

Don't take my word for it. There are millions of projects on Github of just about all sizes. Including quite a few that implement UML editors and IDEs even. Try finding their design documents. You will come up very very short. The larger the project, the less likely it is to have up to date design documentation. You'll find plenty of other documentation and maybe even a wiki of some sorts. But design documentation is not something that is more than an afterthought in the overwhelmingly vast majority of open source and commercial projects (judging from the ones I've been on).

Re: Writing a good design document

#88

Earlier quoted context omitted.

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…

Not sure about the author, but having a few hundreds interviews under my belt (as the interviewer) some of those statements are incomplete. Your example is complete, but if I see statements like: "decreased latency by 5%" I will ask you if are we talking about median or long tail latency. Another example would be "developed a ML model that increased revenue by X%". Here it is missing how the population is affected. I…

You want all that on a resume?

Re: Writing a good design document

#89
post #42
post #37

Earlier quoted context omitted.

> They could easily do the same thing ahead of the meeting, and you'd have much shorter meetings. Amazon’s practice is a reaction to the fact that nobody actually does this. According to the article I read about this years ago, they realized that “creating a strong culture around reading before the meeting” also isn’t possible because many attendees had a meeting before this one, and couldn’t prepare for that meeting…

> Amazon’s practice is a reaction to the fact that nobody actually does this. But isn't that bizarre? I can't think of anything else where we need engineers to do something by a deadline, and we just resign to the fact that they won't do it unless we sit them in a room and babysit them while they do it.

> But isn't that bizarre? I can't think of anything else where we need engineers to do something by a deadline, and we just resign to the fact that they won't do it unless we sit them in a room and babysit them while they do it.

This is practically the point of meetings. Meetings exist as a forcing function to achieve communication that likely could have happened asynchronously but for some reason didn't.

Re: Writing a good design document

#90
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.

Compromise is the term synonymous with "making acceptable tradeoffs”, not optimisation.
Post reply on HN