4 ms·

When useful: Component diagrams, what is connected to what? Activity diagrams, what are the activities that happen, and have they got names? Sequence diagram

When useful: Component diagrams, what is connected to what? Activity diagrams, what are the activities that happen, and have they got names? Sequence diagrams, so microservices on top of microservices, hmm please show me how you get item x? State Diagram, are you sure you have got all the possible state transitions? ERD diagram, Chen style, I don't like it when the look like SQL tables (maybe we don't have/want/need a relational database, so lets not start shaping it like one at the concept stage). The physical/logical models I don't see much value diagramming. BPMN can be useful alternative to Activity diagrams sometimes. edit: left off Use Case diagram, so simple yet seen teams struggle so many times to articulate this. A key thing about doing a diagram or document is that they force you to clarify your understanding. Another rule of thumb is if you are struggling to keep you docs/diagram in sync with your implementation, you have likely made you docs too detailed, its a high level map to guide not a detailed set of instructions on how to construct.

zerkten 5y ago
> A key thing about doing a diagram or document is that they force you to clarify your understanding. Another rule of thumb is if you are struggling to keep you docs/diagram in sync with your implementation, you have likely made you docs too detailed, its a high level map to guide not a detailed set of instructions on how to construct. These are really good points. I've found that refreshing diagrams, even if's a hand drawn update, or modifications, to an older diagram for the new person on the team can be valuable in identifying what is different and getting a sense for how important it may be to redocument (or even refactor) that system. Simply putting dates on diagrams so people aren't guessing is helpful. It goes with doing something like automatic labeling of content in your wiki that's over a certain age so that people are mindful.

zerkten 5y ago

> A key thing about doing a diagram or document is that they force you to clarify your understanding. Another rule of thumb is if you are struggling to keep you docs/diagram in sync with your implementation, you have likely made you docs too detailed, its a high level map to guide not a detailed set of instructions on how to construct. These are really good points. I've found that refreshing diagrams, even if's a hand drawn update, or modifications, to an older diagram for the new person on the team can be valuable in identifying what is different and getting a sense for how important it may be to redocument (or even refactor) that system. Simply putting dates on diagrams so people aren't guessing is helpful. It goes with doing something like automatic labeling of content in your wiki that's over a certain age so that people are mindful.