How to to document conversations, facts and History in the project?

Question

I am working as team leader of developer team for IT department of US based Client. Our main objective is to deliver web based product for customer care department. For current project we have multiple teams and departments working on. Some of the departments are not falling under our organization, they are from different organization and different management where our bosses and managers have less influence and control over them. Each team again has team members who are working from different employers working for this client. Even my team has team members from different employers.

Recently there was churn occurred in the project. We have finalized requirements and got signed off from consumers of the product. But underlying web services design are not supporting the way the current requirements written. With this lot of back and forth, multiple long hours meetings and shared information back and forth to understand each others problems between services team, Business analyst team, product consumers team(customer care team) and internal technical team.

But the problem arises this communication, information exchanged, history behind it is not properly documented. When final plan and requirements derived there seems to be lot of gaps against what we are discussed.

Problems that I am facing right now:

• It is hard to explain and raise questions since the context is always what we have spoken, discussed in some meeting. Many people say “I don’t remember that. Let me check again”
• And even some times they refer some conversation in some meeting. Unfortunately I am also unable to recollect.
• Some times it appears we have talked about same issue or point. But we have deviated to other direction in the meeting and I want to have the conversation in right direction.
• Developers are also some times some times ask “what makes you think this requirement is valid/invalid”. When I refer some conversation happened past with other teams, they look at me,“How can I trust since I don’t know all of that stuff? How can I go based on only your words? Why not there is no concrete documentation"

The above specified problems are few samples and there are many confusions, gaps in the environment. With this given situation how can I properly document, organize the communication, information shared in the meetings and history happened"

Answer 1

First, hold meetings with agendas. I am not advocating thirty page agendas or four hour meetings but a few bullet points for a thirty minute meeting can help people get in the frame of mind, allow unneeded people to skip the meeting, ensure needed people attend and will help you stay on track. If the conversation veers off for more than five minutes, either add a new item on the agenda or create a follow-up meeting with the interested parties only. If you have too many agenda items, prioritize those with the largest impact on the project.

I know meetings get a bad reputation but a well planned and disciplined meeting can be a very effective way making a decision. If you need more than 30 minutes for a meeting, split it up with the first meeting creating options with pros and cons and a follow up meeting with stakeholders to make the decision.

Second, keep minutes of each meeting. You can refer back to the minutes later to understand what was discussed, what the requirements are and so on. Sometimes it can be helpful to mention what was not discussed (e.g. component A but impact on the component A changes on component B will be discussed in another meeting) or why decisions are postponed (e.g. waiting on new budget approval).

A wiki, like Confluence, is great for both agenda setting and minutes. You can create the agenda ahead of time in the same document that people can add to, can enter minutes into the same document against each agenda item then assign action items that appear in people's task lists. The agenda and minutes are searchable. There is a single source of truth, unlike a circulated Word document. A history is kept. People can watch the space or document and get E-mailed when changes occur.

Third, keep a "decision register". A decision register records each major decision, the options, the main reasons why that option was chosen and the stakeholder(s) that made the decision. This can help stakeholders demonstrate leadership and involvement while giving development something to refer back to.

Fourth, do not be afraid to revisit early decisions. Things change. Although I hate to use the "p" word (process), have a small bit of process around this. For example, raise it at a weekly team meeting with the important stakeholders, bring everything they need to make an informed decision then capture it in both the current meeting minutes, a small note in an addendum to the original meeting minutes and in the decision register.

However, I think the biggest problem here is cultural. You appear to have a culture of people being the source of truth rather than documents. That can work in small teams or projects but, as the team or project scales up, this creates a bottleneck and single point of failure. Peoples' memory also atrophies surprisingly quickly. The increased overhead of capturing this information requires (1) discipline and (2) time, both of which can be lacking.

Indeed, many well meaning but misinformed Agile proponents say that documentation is "not agile". This is false. The Agile manifesto emphasizes "working software over comprehensive documentation". The important word here is "comprehensive" - capture the important bits and move on.

To drive this change, you need management support. It is good that you are recognizing this as a team leader but you will likely need to sell this to your manager as well. Decision makers need to realize their decisions are only as good as the product the team creates. This is the inverse of how many decision makers think, as they are generally viewed as senior and implementers (e.g. developers) as junior. A decision that no one can remember or that people disagree on is a poor one, likely to result in a poor product.

Answer 2

I will try to complete @akton's answer.

Regarding meetings and business decisions, if it is not written down, it is not a decision but an opinion. You cannot take business decisions on opinions.

Here are things that work:

• each meeting should have an agenda, defined in such a way that people will need to know: why they are required in the meeting, what will be discussed and what will be decided. The agenda also has to be short and concise.

  • Good example:

    Agenda: decide the format and contents of the report sent to ACME each month Open questions: How many pages should the report take? We have seven possible sections but only 5 should be in the final report. What do we skip?

  • Bad example (doesn't actually tell people how to prepare for the meeting):

    Agenda: the ACME report

• during a meeting, take notes on anything that requires follow-up. (e.g. "Alfred will complete the report of the status of the update and send it by mail by latest, tomorrow morning"). At the end of the meeting, you should have a list of decisions taken and tasks (along with person responsible). Also consider taking short notes on things that are no longer necessary.

• after the meeting go over your notes, then write at least one email with the summary and send it to the meeting participants. If you use other media for this, use that (wiki, post-it notes, whatever).

The important parts: write it down while it's fresh, share it with involved people, store it (in such a way that it is indexable/findable easy).

If there is big controversy in a decision (half the team wants it one way and half another way) then also write down a note on the controversy and what was decided.

•It is hard to explain and raise questions since the context is always what we have spoken, discussed in some meeting. Many people say “I don’t remember that. Let me check again”

Ensure decisions are written, centralized and managed. The "I don't remember that" issue should always be solved by opening the latest spec (what you decided earlier). Conversely, the latest spec should be public and centralized and easily accessible to everyone required. In my last position, this meant a wiki (trac wiki) where there were instructions, decisions, how-tos and so on.

Unfortunately I am also unable to recollect.

The is not recollection issue, but persistence and centralization one. You should have it at your fingertips (and not need to recollect it). Ideally, it should be something that you could throw a quick look over, when going to a meeting, in the middle of a discussion (or meeting) and when you are on the phone.

Some times it appears we have talked about same issue or point.

If you didn't write it down, you haven't taken a decision about it before. This means that everybody will (maybe) remember something of it and have an opinion - not a business decision (because the decision wasn't formalized / written down).

Developers are also some times some times ask “what makes you think this requirement is valid/invalid”.

They are absolutely correct to ask that.

When I refer some conversation happened past with other teams, [...]

Requirements, no matter how informal, should never be a conversation (but something persistent and verifiable).

With this given situation how can I properly document, organize the communication, information shared in the meetings and history happened"

• find a single place for it (website/wiki, specialized software, local IRC server with history, whatever works). This should be easily accessible to everyone and easy to use.

• whenever somebody asks for details, send them a link (or better, instructions on how to search).

Answer 3

You say you have a requirements document. This document is king, it trumps every email, meeting etc. If you have made decisions that change the requirement, then update that document right then (we usually do it during the meeting or the BA does it immediately after the meeting if it is extensive.)

Devs should be required to follow the requirement, code review should include ensuring the requirement was met and QA shoud design tests based on the requirement.

Major changes to the requirement should trigger a process that sends them out to the devs and QA testers as well as the managers or people in the meeting. Requirements changes are inevitable, but should be held to a minumum once development work starts. If necessary push the change out to the next version of the software or a later iteration. Never make requirement changes and assume the people doing the work are aware that you changed something. They don't attend the meetings, they have no way of reading your minds.

Devs cannot properly develop with a requirement that changes by the minute, so make sure the majority of the decisions happen before they start and that changes during dev are those asked for because of a limitation the devs found (such as conflicting requirements or a limitation of the tools used or a clarification of meaning due to questions asked by the devs/qa personnel) or those that are show-stopper urgent.

Answer 4

I just want to add with two links regarding documenting decisions:

1. Documenting Architecture Decisions by Michael Nygard provides a template for documenting architecture (or design) decisions:

   1. Title
   2. Context
   3. Decision
   4. Status
   5. Consequences

2. How Using a Decision Journal can Help you Make Better Decisions by Shane Parrish provides another template you might find useful:

   1. Situation/Context
   2. Problem statement
   3. Variables
   4. Complications
   5. Alternatives
   6. Outcomes
   7. what you expect to happen

Of course you can make your own template. Use it to document at least major decisions in your project.

Note: If I would have enough points I would have written this as a comment, because, yes, this not quite an answer but merely additional information. Downvote me but why delete relevant content?

Update: List template content, add note.