Ask HN: How do you document architecture and design proposals?

https://news.ycombinator.com/item?id=20190646

by abatilo • 7 years ago

3 1 7 years ago

news.ycombinator.com

I always read about how an engineering team should work by documenting their design/architecture for system changes or new features, so that senior engineers/architects can review it and give feedback.

How do you do it on your team? What tools do you use?

How do you manage the conversation/feedback? Do you graph/diagram anything? Do you just write out what the steps are? What about documenting request/response models?

I'd love to get insight into all the ways that people handle this.

davismwfl• 7 years ago

Personally, start with a high level domain model, then a high level block diagram of the architecture (essentially a system model) and then keep breaking it down to the module level. This way people start with the domain understanding what the problems are and what it is they are trying to solve and move into the high level system model to see how it fits together, which leads them to modules that have contracts. Teams should maintain the documentation for anything they work on, and update any changes in assumptions and input/outputs that lets other teams stay up to date.

Key things (especially on modules) to document are any special behavior, inputs, outputs, data needs and any assumptions. I personally like to do it in block diagram because then you can also do flow diagrams as well. This also is nice because you can do a template document to help people. Of course, as a system gets more and more complex this gets tougher sometimes, e.g. microservice architectures with more than 100 services can be tough if you try to go too deep, but if you keep it at the module level and above it is easier to manage and is usable.

Overall to me it isn't really that hard when you are starting fresh, much harder to go back and figure it out later unless you have someone on the team that has the full understanding which gets less and less likely the larger the team/product gets. So then it becomes a major undertaking to get all the people that have knowledge together and figure it out. The advantage is a lot of times you find things that were bad assumptions that changed at some point and are likely causing some unknown issues, so it is still worth all the effort.

As for how to manage it, documents in revision control is one way, tools like Quip are another, just kinda depends on the team etc.

Ask HN: How do you document architecture and design proposals?

Related Stories