Does every engineer have to know UML?
How to stay in balance while documenting your software design
Software documentation is one of the most contractionary topics, especially in the Agile world. Agile Manifesto says that you have to have working software over comprehensive documentation. But does it mean that you don’t need to document your software at all? Rather no
All sorts of software documentation need to cover stakeholders’ needs, but that doesn’t mean that your project needs to be documented in all aspects. Moreover, it most likely means that you need to document only important and non-obvious decisions.
Most of the time engineers and architects use diagrams to represent their design in the most convenient way. And when I’m saying diagrams the first thing that comes to mind is the UML. But is it the only notation you can use for documenting your software? Of course no
Notations
There are three notations for documenting your design. UML is one of the most familiar notations but even taking into account that it has a lot of different diagram types and a pretty clear definition of what blocks and relations mean in each of them — it’s semiformal notation.
It means that you can’t generate any working piece of software from the documentation itself automatically, but it’s wildly used because UML gives us a structured and clear way to describe our architecture and its aspects. And what’s the formal notation is? There are a lot of notations related to a formal class, but it’s pretty costly to use it for all the projects and it doesn’t make sense. One of them that you can read about is AADL
And of course, we have an informal notation for our documentation. I suppose you heard at least once about blocks and lines diagrams. If no — you read about it just a moment ago :) But if we talk seriously it’s the most widely used type of diagram. It has no restrictions and can be applied to all sorts of information you want. But if it’s so cool for what reason do we need UML?
Blocks and Lines
First of all, let’s briefly look at informal notation to understand what we can do with it and what’s the building blocks. As in any notations, in informal notation, we have blocks — components, modules, environments, etc, and relations between them — lines.
As you can see we can build a pretty good diagram even without UML that can show interactions between users and our system, but something remains unclear. What are the blocks mean? Modules and classes? Services and components? Here is room for assumptions and the only thing we forgot about is the Keys, for our diagram to make our diagram clear. Keys should describe what blocks and lines mean in a particular picture.
Here it is, much better. And let’s step back to our question, if we can use the informal notation why do we need to know UML?
Conclusion
Informal notation gives you some freedom in making your diagrams, but with this freedom you have to make a commitment to describing all kinds of blocks and lines you choose to give your stakeholders a clear vision of what you were trying to show them.
And on the other hand, UML gives you already defined framework that most likely your stakeholders already know, or at least they can find its descriptions freely. Like OOD patterns it gives you a dictionary that you can use and be sure that it’s wildly used and recognizable.
Honestly saying — it’s up to you which to choose, there is no one right way. For the 99% informal notation will be enough, but there is no case where you can’t apply UML instead of blocks’n’lines diagrams, so if you don’t know UML — you’ve already known what to do with your diagrams to make them clear, but if you want to make your life easier and develop your documenting skill- UML is a good one.
Thank you for reading this article!
If you want me to continue writing about software documentation, design, SDLC, and all topics around feel free to clap, subscribe and leave your comments.
