Developing a software system by first creating a large number of detailed diagrams is an approach that, in our experience, does not compare favourably to the alternatives. However, describing a particularly complex and intricate part of the system with a diagram is usually a good idea, and the UML itself offers a number of useful and commonly understood diagrams. We like PlantUML for creating these diagrams because it allows expressing the intent behind the diagrams in a clear textual form, without having to fiddle with overloaded graphical tools. Having a textual form also allows versioning and storage alongside the source code.
I've always been a fan of Web Sequence Diagrams, so was glad to see here an open source tool which can generate more than just sequence diagrams.
Here's how you can easily generate diagrams from text with Python
Install Python plantuml:
pip install plantuml
Create a sequence diagram:
title Authentication Sequence Alice->Bob: Authentication Request note right of Bob: Bob thinks about it Bob->Alice: Authentication Response
Generate the diagram:
python -m plantuml diagram.txt