
Ask HN: How do you document architecture and design proposals? - abatilo
I always read about how an engineering team should work by documenting their design&#x2F;architecture for system changes or new features, so that senior engineers&#x2F;architects can review it and give feedback.<p>How do you do it on your team? What tools do you use?<p>How do you manage the conversation&#x2F;feedback? Do you graph&#x2F;diagram anything? Do you just write out what the steps are? What about documenting request&#x2F;response models?<p>I&#x27;d love to get insight into all the ways that people handle this.
======
davismwfl
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.

