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.
1 comment:
!!
I am a young software engineer, currently trying to move towards an architect role. I've had experience in huge support project for system that are 3, 10, even 20 years old. And one thing that I find missing, is the project diary!
Through my experience however, it is better to separate the diary into three separate logs. The first diary is for the non-technical aspect of the project, and is kept by the project manager. This is basically for the 'history' of the project. They make perfect addendum to the requirement document.
The second diary is for the technical aspect of the project, and should be kept by the architect. They capture design decisions, modification to the architecture etc. They can simply be a series of the various architecture diagrams captured in various stages of the project with explanation from day one until current. Through these series of entries you can see the history of the system architecture. They made perfect addendum to the original Architecture Document.
The last log, is for the code maintenance level. If a rigid source versioning system is in place, this log should capture information around every source tagging activity. I.e why is it tagged, what are the updates implemented in the current version, which one is excluded, which one is still buggy, etc. Through here you can keep track of the history of the implementation, and they make really good adendum to the project developer handbook, or to the support guide!
Post a Comment