Did you ever experience those never ending and and continuous discussions about project topics and decisions which you thought had been already addressed?
Did you ever read an architecture document feeling a little bit confused or lost, because you couldn't remember the rationale of all those decisions?
I am sure, you know what I mean. The problem with software development projects is that there are basically two sources of information besides personal communication:
- Meeting Minutes
- Architecture Documents
Unfortunately, most architecture documents only describe the what, but not the how or why. Meeting Minutes strive for brevity and often don't include all those discussions. In addition, spontaneous meetings of project (sub) teams are often not documented at all.
Your gut feeling may tell you that something is missing here.
What I propose for development projects is an additional document, which I call "Project Diary". This document does not need to be very formal. It should not describe what is already available in other documents (meeting minutes, architecture documents) but instead refer to these sources. And, of course, architecture documents and meeting minutes, should also refer to the project diary. Its sole purpose is to complement these aforementioned documents by adding information such as alternatives discussed for solving a particular problem and the reason why a specific decision was preferred.
The organization of such project diaries may be by date or by topic or by both.
I don't recommend any specific template to use. My experience with all kind of project documents tells me that it is more important to come up with a uniform, complete and consistent style than to strictly follow a specific template. Just take your style of choice.
Sometimes, project members don't like the additional efforts of a project diary, especially in very small teams. In these cases I often have written a project diary without telling anyone. As soon as critical situations or fruitless discussions appeared, I would then just read from my project diary. This way, I could convince many people that a project diary offers more value than costs.