For tech leads and architects
Review a design with its dependencies in view
Before you split a service, check its dependencies and which docs need to change. ArchDocs tracks connections between shared objects in saved diagrams so you can review the proposal against the system you've documented.
Sound familiar?
- We've renamed this service, but the diagrams I found still use the old name.
- I know we ruled out that design. I can't find the reason.
- The proposal looks fine on its own. What else calls this service?
Give each service one definition
Define a service as a shared object and reference it in each diagram. Open its Used in docs tab to find the documents that need a review.
Keep the reason with the service
Record the options and trade-offs in an architecture decision record, then link it to the affected objects. When a decision changes, link its replacement so the next reviewer can follow the history.
Review the diagram as YAML
Open the YAML beside the canvas to inspect the diagram's source. Edit it there or keep a copy in Git to review changes in a pull request.
A design review, start to finish
Open the service object and check its documented dependencies.
Draft the proposed design in a new document.
Write the decision and link the affected objects.
Share the proposal with the engineers who own the callers.
C4 system context
Map an outreach platform, the person who uses it and its email provider.