Architecture & Software Documentation, Part II – The Database

[Reading Time: 15mn]

Introduction

I have introduced the topic of documenting software artefacts in my previous blog post. As I said, the purpose of a good documentation is to communicate – to your technical peers, to your boss, to your sponsors.

But a good documentation set is hard to achieve and then, to maintain. It should live as close to the actual code as possible. A good deal can be obtained through reverse engineering to / from UML when your project is object-oriented. But let’s face it, we live in a polyglot programming world. At least some layers in our software design won’t be amenable to UML because they don’t use object-orientation design. The canonical example being: how would you go about documenting your SQL-based data model?

Continue reading “Architecture & Software Documentation, Part II – The Database”

Architecture and Software Documentation

[Reading Time: 15mn]

Introduction

In software development projects, documentation is often considered as an after-thought – if not completely ignored. As professionals, we all know that documenting is part of the design and development activity, much like pushing artifacts to production is part of the development process. Of course, I am not talking about the project’s own documentation like specifications / requirements or sponsors meeting minutes or project planning. They are obviously necessary, but not what I want to review here. No, here I am talking about documenting the design and the code. And remember, we have all been told that it is not only good practice, but also contributes to the overall quality of the project. Not convinced? Okay, let me tell you a story we all know already.

Continue reading “Architecture and Software Documentation”