I wish i was allowed by my employer /organization/work culture to write DD in a format this reasonable.
Writing a good design document
21–30 of 152 posts
Re: Writing a good design document
#22Taking a class in technical writing greatly improved my ability to summarize written documents. The course emphasized a “cut with a red pen” approach (write, cross out, rewrite), which focused on using as few words as possible to communicate concepts and ideas clearly. This method has multiple layers and becomes easier with practice. I also try to share this knowledge with the teams I work with, but it’s important to remember that it’s a skill that requires regular training.
Re: Writing a good design document
#23Solid advice on clarity and editing. The only gap is what happens after the doc is approved? Without upkeep it decays into "design archaeology." A few years ago, Andrew Harmel-Law wrote about an interesting approach to scaling architecture conversationally, which includes lightweight Architecture Decision Records (ADRs) as one tool that could help here. ADRs live beside the code (adr/001-use-postgres.md) and capture context, decision, and status in a format short enough to, I think, revisit in every PR and easy to supersede when reality changes so the original rationale stays searchable months later.
Here’s a link to Harmel-Laws’post if anyone's interested: https://martinfowler.com/articles/scaling-architecture-conve...
Re: Writing a good design document
#24Solid advice on clarity and editing. The only gap is what happens after the doc is approved? Without upkeep it decays into "design archaeology." A few years ago, Andrew Harmel-Law wrote about an interesting approach to scaling architecture conversationally, which includes lightweight Architecture Decision Records (ADRs) as one tool that could help here. ADRs live beside the code (adr/001-use-postgres.md) and capture…
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:
https://www.thoughtworks.com/radar/techniques/lightweight-ar...
and eventually end up with this beauty (big download button at the bottom of the page from above):
https://www.thoughtworks.com/content/dam/thoughtworks/docume...
Would you mind pointing us at an actual definition of ADRs, please?
Re: Writing a good design document
#25It's worth noting the author led the implementation of the file system at the bottom of S3.
Re: Writing a good design document
#26Earlier quoted context omitted.
99% of bullet points containing numbers in a resume are made up, hamfisted BS, the other 1% cannot be attributed to a single individual so putting them in a personal resume is silly.
It’s so dumb. There is no way to verify the numbers, and yet, this stupidity weaseled its way into the LinkedIn cinematic universe of corporate bullshit. The same point but without the “X by Y%” hits the same for me— besides I know what questions to ask to judge if you are actually capable of moving the needle, which is all I care about as a conductor of interviews.
the problem is CVs are screened by non-tech HR/recruiters, who lack the capacity to screen candidates. Because it is much easier to apply online with one click, each position is spammed with millions of CVs.
in response, for HR it is much easier to filter out CV if it lacks style, not substance. Therefore they look at bullet points like "Done X by Y%".
The proper way should be to limit the intake funnel: accept only a few applications per job, so that they can be screened properly by HRs by calling them, and talking to them and properly screening (old school style), instead of tossing their resume to the bin after 15 sec quick review
Re: Writing a good design document
#27Solid advice on clarity and editing. The only gap is what happens after the doc is approved? Without upkeep it decays into "design archaeology." A few years ago, Andrew Harmel-Law wrote about an interesting approach to scaling architecture conversationally, which includes lightweight Architecture Decision Records (ADRs) as one tool that could help here. ADRs live beside the code (adr/001-use-postgres.md) and capture…
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 documents, frequently stored in source code repositories alongside the artefacts they describe." He also provides a handy "Elements of an ADR" table. Let me know if you're still having problems finding it.
Re: Writing a good design document
#28As a design reviewer, I think all design authors should internalize this concept: > But a good doc will lay out the problem and mental models in a way that the solution that took weeks of hard thought to invent will be clear to the reader by the time the doc presents it. Perhaps my favorite quote is: "If I had more time, I would have written a shorter letter." Design docs should make complex things simple. They shoul…
I prefer "more time, shorter letter"
Re: Writing a good design document
#29The opposite of this is a culture where "we just work it out in slack."
Re: Writing a good design document
#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'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.
And doing it synchronously means everyone either sits idle until the slowest reader is ready or not everyone gets to finish in time. And "slowest reader" isn't even just about reading speed. Presumably, some people can understand the document more quickly because they have more context.
In design reviews at Google, it was obvious that the majority of attendees came unprepared and were reading the docs for the first time while their teammates were discussing the doc. I suspect that the reason was that Google just didn't have a strong docs culture, and leads/managers quietly tolerated people coming unprepared (and sometimes, they themselves were unprepared).
I've never seen it done in practice, but I don't think it would be hard to have the best of both worlds where people review docs ahead of the review meeting, but there are strong cultural norms around reading docs ahead of time so the meeting is just for discussion, not just for reading or pretending that you've read.