Introduction

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.