If you’ve been following along, we’ve explored the power of Markdown and AsciiDoc in our previous articles. Now, we turn our focus to PlantUML, a versatile tool that takes your technical documentation to the next level by integrating diagrams seamlessly into your workflow.
PlantUML is a flexible tool that makes it easy and quick to make different kinds of diagrams using a simple and intuitive language. Its capabilities and its design allowing to define diagrams in simple text files make it a valuable asset for technical documentation.
One of its biggest advantages is how easily it integrates with version control systems like Git. This means you can store your diagrams right alongside your code, making it simple to review changes, track versions, and collaborate with others. It's no wonder so many professionals prefer using PlantUML for their documentation needs—it makes the whole process smoother and more efficient.
PlantUML: A Brief Overview
PlantUML is not just another diagramming tool; it's a comprehensive text-to-diagram system that allows users to write simple, human-readable text that is then converted into a wide variety of diagrams. The language is designed to be intuitive and closely mirrors the structures found in traditional UML diagrams, making it accessible even for those new to diagramming.
You can find below how you can use simple text following the PlantUML syntax to make accurate and visually appealing diagrams:
@startuml
start
:Init Phase;
:Transfer Phase;
note right
long running activity,
process requires signal to proceed
end note
:Termination Phase;
stop
@enduml
Use Cases for PlantUML in Software Development
PlantUML has found its place across various industries and user groups, from individual developers to large enterprises, due to the wide array of diagrams it supports and its ability to integrate with documentation workflows on code hosting platforms like GitHub or wiki tools like Confluence.
Since PlantUML diagrams are text-based, they can indeed be easily integrated into version control systems like Git, enabling collaborative diagram editing, change tracking, and integration with CI/CD pipelines.
Here are a few example use cases for which PlantUML can bring significant value:
- Workflows and processes documentation: PlantUML supports a variety of UML diagrams, including sequence, use case, class, and activity diagrams. This makes it ideal for modelling both technical and business topics. This can include representing technical processes like API calls, modelling user stories or expliciting use cases for features to name a few examples.
- Architecture Documentation: The ability to create component and deployment diagrams allows teams to document system architecture, representing components and their interaction in a visually efficient way.
- Database Design: PlantUML’s support for entity-relationship diagrams is particularly useful in designing and visualizing databases’ structures.
- Planning and prototyping: Wireframe and Gantt diagrams supported by PlantUML allow for simple UI prototyping and timeline illustrations that can be helpful in the product management processes or to create previews of roadmaps and features planning.
Integration with Git and Confluence
Git and GitHub: The text-based nature of PlantUML makes it ideal for integration with Git, allowing teams to manage diagrams alongside code. GitHub, for instance, even automatically renders PlantUML diagrams in Markdown files, making them visible directly within repositories.
Confluence: With tools like the Include Bitbucket for Confluence app, PlantUML diagrams hosted on git platforms can be embedded in Confluence pages. This integration supports dynamic documentation processes where diagrams are updated in sync with project development.
Here’s how to integrate Bitbucket-hosted PlantUML diagrams into Confluence using our app Include Bitbucket for Confluence:
- Connect to Bitbucket Cloud and/or Connect to Bitbucket DC (for private resources)
- Copy/ paste the Bitbucket url of your PlantUML file
The process is simple from a user perspective but from a technical perspective it is a complex process involving multiple systems.
To clarify this for our technical audience, we've chosen to use a sequence diagram created with PlantUML. This tool is ideal for visually representing intricate workflows, making the entire process much easier to understand.
In the example below, you'll see that same PlantUML diagram hosted on Bitbucket Cloud and embedded in a Confluence page, which clearly and simply illustrates how our app connects Bitbucket Cloud from Confluence Cloud.
Our Findings
PlantUML has proven to be for us a very convenient and reliable way to convey complex ideas in an efficient way that integrates very well with git hosted documentation resources. In a nutshell, here are some of the main upsides of using PlantUML:
Text-to-Graphic Correlation: The close resemblance between text inputs and the resulting diagrams ensures that what you type is what you get, making the diagramming process intuitive and quick.
Ease of Editing: Since diagrams are generated from text, editing and updating them is straightforward, requiring only text modifications rather than complex graphical adjustments.
Support for Multiple Diagram Types: Beyond UML, PlantUML also supports various other diagram types, such as JSON, YAML, network diagrams, and Gantt charts, making it a versatile tool for diverse documentation needs.
Customization: With options for customizing diagram appearance, including colors, fonts, and shapes, PlantUML allows for tailored documentation that aligns with corporate branding or project-specific styles.
Explore how you can leverage these capabilities in your documentation process too by integrating PlantUML with Confluence using the Include Bitbucket for Confluence app.