The problem with documentation⌗

Sketching an idea you just had, or drawing a pretty diagram showing your current system in detail is always nice because it helps you understand the system in more detail.

The moment you develop a system or a new idea is often easily captured with a diagram. But as you continue developing, the diagrams can often become out-of-date or mismatch the current state of reality because people tend to forget or just don’t care.

Not everyone wants to open a graphical editor to move around some things, draw arrows and whatnot.

Developers (like you?) prefer something more minimal in most cases. Non-technically inclined people may be unable to understand those minimalistic or programmed solutions and can not help in maintaining.

What is PlantUML:⌗

PlantUML is an open-source project, which allows you to easily create UML diagrams without a graphical tool. Diagrams are created through .puml files which look like this:

@startuml
Alice -> Bob: Authentication Request
Alice <-- Bob: Authentication Response
@enduml

As you can see, it has a fairly easy to read syntax which makes it an ideal choice for documentation because the entry threshold is very low. Non-technically inclined people will also be able to help you in maintaining the current state of reality.

⚠️ They may even be able to give you a diagram of what they think a process should look like before you start implementing.

Usage⌗

Web⌗

Those .puml files can be used with a web based PlantUML server that’s free to use like: THIS ONE

Local installation⌗

You can use a local PlantUML server to generate the images locally. To do this, you first need to install Java & Graphviz and then download the PlantUML jar file.

After installing those things you can create your first .puml file and generate a .png from it.

java -jar <plantuml.jar> <diagram.puml>
(replace the placeholders with your values)

Check out this docker image to use a container for image generation.

⚠️ If you’re unsure how to use Docker,
check out our getting-started-with-docker beginners guide.

Usecases⌗

There are many potential usecases for using PlantUML. Be it in your company or in private projects. Generally speaking, PlantUML is used to create diagrams that help you understand specific aspects of something. In software development that could be class diagrams of business objects or a sequence diagram showing a specific process in more detail. This can be especially useful to show the order of communication between different participants.