3 ms·

I would ask the documentation fairy to come up with sequence diagrams for the most common flows/use cases. That used to be the winning argument whenever i have

I would ask the documentation fairy to come up with sequence diagrams for the most common flows/use cases. That used to be the winning argument whenever i have to come up with some docs. I think that sequence diagrams are the killer feature of UML -everyone gets the message.

jnxx 7y ago
What is it what makes these sequence diagrams especially important in your experience?
- MichaelMoser123 7y ago
  They explain the dynamics of a system, how the parts fit together and show the responsibility of each component in the context of the action (use case)
bob1029 7y ago
I share this sentiment regarding diagrams. Any time I sense that a design or requirements discussion is starting to lose track of all the various edge cases of a particular business process, I will draw out a state diagram of that process and put it into an email or message to the team. 9/10 times this either immediately ends the back-and-forth, or quickly narrows down the actual concerns to a few particular items. I am consistently amazed by how quickly these diagrams can convey complex business requirements to non-technical people. I could write 30 pages of email, or draw 1 state machine on my whiteboard and snap a photo of it. Someone should try to run the math on information density of a state diagram vs a verbal or written communication of the same requirements. I would bet there are a few orders of magnitude of delta in there based on my experiences.
- proverbialbunny 7y ago
  If you don't mind the curiosity, what software do you use to draw state diagrams?
  - bob1029 7y ago
    I just draw them on a whiteboard next to my desk and then capture using something like Office Lens (it has a really good mode for whiteboard). It's way faster and easier than doing it in software. This allows you to iterate really quickly using rough sketch diagrams (also helps to open your mind up since it's just you and the board), and then once everyone agrees on the design someone can take your whiteboard sketch and turn it into a computer-generated diagram for the final documentation. We have actually found very few cases where we need to have 'formalized' diagrams generated using software. Most of them just live in our GitHub issues and pull requests. With enough practice, your hand-drawn diagrams can look good enough to ship directly to a client for approval. If we do need to make a computer-generated drawing, we just use some web tool like draw.io or use a local copy of Visio.
  - onetom 7y ago
    I can highly recommend http://plantuml.com/ http://plantuml.com/ because it has support for other types of diagrams too, not just sequence diagrams. It's open source and also cross platform, since it's written in Java. It has command-line interface too and integrates with most popular IDEs. You can host your own rendering server too and just reference your diagrams as URLs (https://github.com/plantuml/plantuml-server https://github.com/plantuml/plantuml-server). There is a 3rd party, independent rendering server integrated with a web editor. I recommend that if you want to quickly test PlantUML: https://www.planttext.com/ https://www.planttext.com/

jnxx 7y ago

What is it what makes these sequence diagrams especially important in your experience?

MichaelMoser123 7y ago
They explain the dynamics of a system, how the parts fit together and show the responsibility of each component in the context of the action (use case)

bob1029 7y ago

I share this sentiment regarding diagrams. Any time I sense that a design or requirements discussion is starting to lose track of all the various edge cases of a particular business process, I will draw out a state diagram of that process and put it into an email or message to the team. 9/10 times this either immediately ends the back-and-forth, or quickly narrows down the actual concerns to a few particular items. I am consistently amazed by how quickly these diagrams can convey complex business requirements to non-technical people. I could write 30 pages of email, or draw 1 state machine on my whiteboard and snap a photo of it. Someone should try to run the math on information density of a state diagram vs a verbal or written communication of the same requirements. I would bet there are a few orders of magnitude of delta in there based on my experiences.

proverbialbunny 7y ago
If you don't mind the curiosity, what software do you use to draw state diagrams?
- bob1029 7y ago
  I just draw them on a whiteboard next to my desk and then capture using something like Office Lens (it has a really good mode for whiteboard). It's way faster and easier than doing it in software. This allows you to iterate really quickly using rough sketch diagrams (also helps to open your mind up since it's just you and the board), and then once everyone agrees on the design someone can take your whiteboard sketch and turn it into a computer-generated diagram for the final documentation. We have actually found very few cases where we need to have 'formalized' diagrams generated using software. Most of them just live in our GitHub issues and pull requests. With enough practice, your hand-drawn diagrams can look good enough to ship directly to a client for approval. If we do need to make a computer-generated drawing, we just use some web tool like draw.io or use a local copy of Visio.
- onetom 7y ago
  I can highly recommend http://plantuml.com/ http://plantuml.com/ because it has support for other types of diagrams too, not just sequence diagrams. It's open source and also cross platform, since it's written in Java. It has command-line interface too and integrates with most popular IDEs. You can host your own rendering server too and just reference your diagrams as URLs (https://github.com/plantuml/plantuml-server https://github.com/plantuml/plantuml-server). There is a 3rd party, independent rendering server integrated with a web editor. I recommend that if you want to quickly test PlantUML: https://www.planttext.com/ https://www.planttext.com/