How to describe software architecture

23 june 2022
Jakub Rojek Jakub Rojek
Photo by Alexa Wonga on Unsplash (
Categories: IT analysis, Programming, Methodologies


Documentation of IT projects is a never-ending story and can be considered from many aspects. No one is likely to doubt that well-prepared and described guidelines often even save digital ventures. However, the scope of the prepared documentation and its level of detail is a contentious issue. After all, it should be remembered that the process of producing a specification or other outline should not take too long due to the fact that at a certain point and under the right conditions it becomes unprofitable. Of course, it is difficult to define a rule that would clearly describe this, and I would even be tempted to say that it is impossible. The whole process, as well as the timing of documentation, is a matter of feeling and experience, while it is not without reason that one of the points of the Agile Manifesto says that "working software is more important than detailed documentation". On the other hand, we know from experience that lack of description in any form is even worse.

That's why you should first focus on highlighting the aspects that should be documented and the effort spent on this process will really pay off in the future. At this point, most of you will have a red light in your head signed "requirements specification", and that's a very good clue - it's a basic set of information that is developed in the form of a text document, and one of the methods of creating such was very well described on our blog by Piotr Miklosik (the HANSA method). On the other hand, there are IT projects where writing down only the requirements is not enough - it is necessary to address other areas of software as well, and one of them is architecture. Unfortunately, while many people know how to (at least more or less) prepare a requirements specification, and an equally large bunch of specialists are familiar with code, the knowledge of documenting the more technical side is not so common.

In today's article, we'll show ourselves one approach to specifying architecture - we'll describe an approach used at us, at Wilda Software, and which has worked well in several projects and at different levels of abstraction. It is also being improved all the time, so that in the future it will even better enable us to achieve what is already possible as I write these words. And for dessert (or right away, if you're impatient), I invite you to download a sample template document, that summarizes the knowledge described in this text.

Further article available only in Polish at the following link.

Best regards and thank you - Jakub Rojek.

We can do quite a bit and what is more, our skills and resources are at your disposal. Take a peek at what we can offer you.

About author

Jakub Rojek

Lead programmer and co-owner of Wilda Software, with many years of experience in software creation and development, but also in writing texts for various blogs. A trained analyst and IT systems architect. At the same time he is a graduate of Poznan University of Technology and occasionally teaches at this university. In his free time, he enjoys playing video games (mainly card games), reading books, watching american football and e-sport, discovering heavier music, and pointing out other people's language mistakes.

Jakub Rojek