Documenting a project well is one of the most important aspects of the development lifecycle of any project as at the end of the day this will be shared and communicated with all the stakeholders, for example, clients, project managers, other developers etc whosoever associated with the project. Now descriptive and easy to understand images and diagrams are one of the most important features of any well-written document as they convey more than a thousand words. In this article, we’ll discuss one python package called Diagrams that will make it easy for you to create and maintain technical diagrams. Although this is a python package, it can be used for any project irrespective of the tech stack as we are never going to run the code on a production server.
Why python Diagrams?
Before delving deeper, we need to understand how this package exactly can help us and why would we want to use it in the first place over other traditional online and offline tools (e.g MS paint) etc. I feel below 5 main points makes the python Diagrams stand out from traditional tools.
For a quick and simple diagram traditional tool might just work fine but it becomes extremely difficult to describe a project with complex architecture/workflow and it becomes almost impossible to draw a diagram after a certain level of complexity. Python diagrams come here to rescue us as it enables us to create a diagram as code and like any well-written code, this also can be made modular, scalable and maintainable.
For a traditional drawing tool, it becomes a major challenge to maintain a diagram as the project become more and more complex and new component and interrelation amongst them get added to the project it becomes almost impossible to scale and maintain it. On the other hand, for python Diagrams, it’s pretty easy to extend the code as per need and it passes the test of time.
Python Diagrams offers much more flexibility. For example, if someone wants to focus on a small section of a large diagram. It’s easy to comment out part of the code and focus only on the required portion. For the same reason, it becomes much easier to try out different things and experiment with Diagrams.
For most of the traditional drawing tools, the options to depict a component are very limited which makes it difficult to follow as the diagram gets more complex. For the python Diagrams there huge collection to depict a component, cluster them for better understandability.
Code is reusable and version control is easier just like any other code.
Diagram requires the system to have python 3.6 or higher. In case you don’t already have it you can download and install the required version from here.
Secondly, you need to install an open-source tool to draw graphs, which is used by the Diagrams package under the hood called Graphviz. This can be downloaded and installed from here. Just a word of caution that installing Graphviz using a python package manager like pip might not work.