Hitchhiker's Guide to Software Architecture and Everything Else - by Michael Stal

Thursday, November 02, 2006

Architect's Project Diary

Have you ever been in a meeting where participants discussed a topic which already had been discussed several times before but no one was sure what the concrete decision had been. If yes, didn't you consider that recurring and endless discussions a total waste of your time? To be honest, this is something you will also experience in your family life. But isn't there something we can do to avoid these unnecessary discussions? As software development projects are filled with meetings, the propability of such discussions is tremendously higher which is a good force and motivation to think about countermeasures. What I consider extremely helpful, is a kind of project diary. Within a team, whenever you are deciding on important issues or on issues which you know might raise further discussions, you should document these decisions using a project diary. Mention who was involved in the decision process, what alternatives had beed discussed, which ones were ruled out and which ones accepted. Explain the "what" but also the "why" in this context. Obviously, it doesn't make sense to document everything with all details. Fundamental decisions, however, need appropriate documentation in your diary. You might structure your diary simply as a list of meeting minutes or structure it using topic areas, whatever fits your needs. The advantage of such a diary is that you can understand decisions even a long time later and explain to people why exactly that decision had been taken. Or the other way round: If your requirements or your project context have changed and you need to change previous decisions, using the diary you might get a clue which decisions must then be "refactored". Anyway, a diary is absolutely helpful, when done appropriately and without unnecessary details.


  • +1. An obvious and in my experience very useful approach to this is to use an internal blog for this kind of project rationale documentation.

    By Anonymous Anonymous, at 3:41 PM  

Post a Comment

<< Home