The Research Team's Guide to Shared Documentation

By Dr. Zubair Khalid, DVM, MS, PhD · 2026-11-11

By the end of this guide you will be able to set up a shared documentation system for your research team, write a project charter and decision log, keep meeting notes that people actually read, and use version control so that no document ever has a name like protocol_FINAL_v3_REVISED.docx. You will need a computer with Git installed, a shared folder or repository host such as GitHub, GitLab, or an institutional server, and about two hours for the initial setup.

Shared documentation for research teams is the practice of keeping every working document (protocols, decisions, meeting notes, data definitions, and analysis records) in one place, in predictable formats, with clear ownership. Teams that do this well spend less time reconstructing what happened and more time doing the work. Teams that skip it routinely lose protocols when a student graduates, repeat analyses because nobody recorded why a filter was applied, and struggle to write manuscripts months after the underlying decisions were made.

This guide walks through the whole system, step by step, and ends with the mistakes and limitations you should plan for from day one.

What Shared Documentation Actually Means

Shared documentation has four properties that distinguish it from a folder of scattered files.

Single home. Each document lives in one place. If a protocol exists in three copies on three laptops, the team has zero protocols, because nobody knows which one is current.

Predictable format. Anyone joining the team can find the decision log, the data dictionary, and the meeting notes without asking. Standardized templates are the mechanism for this. A dental hospital that introduced four standard proforma templates at fixed stages of its patient pathway reported better compliance with local standard operating procedures, more consistent documentation, and stronger data collection [1]. The same logic transfers directly to research records.

Clear ownership. Every document has one named person responsible for keeping it current. Shared ownership of a document usually means nobody owns it.

Written rationale. Documents record not just what was decided but why. This is what separates documentation from storage.

A useful vocabulary list before we begin:

• SOP (standard operating procedure): a written, step-by-step instruction for a recurring task, such as sample processing or data entry.
• Decision log: a running, numbered record of significant choices, their rationale, and who made them.
• Data dictionary: a table defining every variable in a dataset, including units and allowed values.
• Version control: software, almost always Git, that records every change to files with a timestamp, an author, and a message.

Why Research Teams Lose Knowledge

The problem shared documentation solves is well described in the research literature, even though it is rarely called "documentation."

Participatory and co-produced research projects, which bring patients, community members, and professionals into the team, succeed when communication is transparent, contributions are visibly used, and tasks are accessible [2]. Those conditions are impossible to meet when knowledge sits in private inboxes. Convergence research programs funded through the US National Science Foundation's Coastlines and People program report similar lessons: teams need inclusive communication practices, deliberate effort to build shared understanding, and plans that expect delays and flexibility [3].

The cost of poor documentation shows up in concrete ways. A qualitative study of interprofessional ALS clinics found that structured documentation was one of the systems-level facilitators of effective team communication, alongside frequent, multimodal contact between team members [4]. Conversely, a cross-case analysis of eight governmental emergency medical teams in the WHO European Region could only compare organizational structures and coordination because the teams were willing and able to share their internal documents in a structured way [5]. Teams that document well can be studied, audited, improved, and joined. Teams that do not become opaque even to themselves.

There is also a proportionality argument. The revised ICH Good Clinical Practice guideline E6(R3), analyzed in a joint ESMO and ASCO consensus statement, pushes clinical research toward documentation that is proportional to risk and avoids unnecessary administrative burden [6]. More documentation is not automatically better. The goal is documentation that a reasonable reviewer, collaborator, or successor can use.

Shared Documentation for Research Teams, Step by Step

This walkthrough builds a complete, minimal system in one repository. It assumes a small to mid-sized academic team, but the structure works for clinical, lab, and computational projects alike.

Step 1: Create the repository and folder structure

Open a terminal and run:

mkdir -p my-project/{admin,protocols,decisions,data-docs,notes,templates}
cd my-project
git init

Expected output:

Initialized empty Git repository in /home/you/my-project/.git/

The six folders have fixed jobs:

Push this to a shared host so every member has the same copy:

git remote add origin [email protected]:yourlab/my-project.git
git push -u origin main

Step 2: Write the project charter from a research project plan template

Create admin/charter.md. This is your research project plan template, and every new project in the lab should copy it. A working example:

# Project Charter

project_name: Myocardial fibrosis in aged mice
project_code: FIB-2026-01
lead: Dr. A. Rivera
deputy: J. Chen (graduate student)

roles:
  - name: Dr. A. Rivera
    role: principal investigator, final decision authority
  - name: J. Chen
    role: day-to-day lead, protocol owner, data manager
  - name: M. Osei
    role: statistician, analysis plan owner

milestones:
  - date: 2026-12-15
    item: protocol and SOPs approved
  - date: 2027-01-10
    item: data collection begins
  - date: 2027-03-01
    item: primary analysis complete

data_sources:
  - in vivo imaging, weekly
  - histology at endpoint

change_control: >
  Any change to milestones or primary endpoints is recorded
  in decisions/decisions.md with date, rationale, and approver.

The change_control field matters more than it looks. It forces the charter and the decision log to reference each other, which keeps either from drifting.

Step 3: Write a README that routes people

Create a top-level README.md that answers three questions in under ten lines: where is the current protocol, where do I record a decision, and who do I ask. New team members should be able to orient themselves by reading this file alone. The citizen science literature on involving older adults in health research identifies training and ongoing support, rather than technical tooling, as the main barrier to participation [7], and a clear README is the cheapest ongoing support a team can provide.

Step 4: Start the decision log

Create decisions/decisions.md with entries in a fixed format:

# Decision Log

## D-003
- date: 2026-11-08
- decision: Exclude animals with baseline imaging artifact above grade 2
- rationale: Artifact at this grade confounds fibrosis quantification,
  per radiologist review of the pilot cohort
- decided_by: J. Chen, approved by A. Rivera
- affects: protocols/imaging-sop.md section 4, analysis plan
- status: active

The rules that make a decision log work:

1. Entries are numbered and never reordered or deleted. A reversed decision gets a new entry that supersedes the old one.
2. Every entry names at least one affected document, so stale protocols get updated the same day.
3. The entry is written by the person who made the decision, at the time of the decision, not reconstructed later.

Step 5: Adopt version control habits

The point of Git is that every file change carries an author, a timestamp, and a reason. The essential commands:

git add decisions/decisions.md
git commit -m "D-003: exclude artifact grade >2 from imaging cohort"
git push

Expected output:

[main a1b2c3d] D-003: exclude artifact grade >2 from imaging cohort
 1 file changed, 7 insertions(+)

Step 6: Build the data dictionary before collection starts

Create data-docs/dictionary.md with one row per variable:

Large-scale studies increasingly automate this. The California Teachers Study built a researcher-facing platform that guides users through the project lifecycle and automatically generates custom datasets, code, data dictionaries, and documentation [8]. Most teams cannot build such a platform, but they can copy its principle: the dictionary should be generated from or checked against the data, never typed from memory.

Step 7: Standardize meeting notes around observable behaviors

What makes a team meeting productive is not the agenda template but the behavior around it. A Danish study of interdisciplinary home nursing teams, observing 64 structured team meetings across 16 teams, identified 36 concrete observable actions that well-functioning teams use, grouped into four behavior sets [9]. Translate a few of those observable actions into your note template:

# Meeting Notes: 2026-11-10

attendees: A. Rivera, J. Chen, M. Osei, community partner K. Doyle

## Decisions made today
- D-004 recorded: move imaging start to January (owner: J. Chen)

## Tasks
- [ ] J. Chen: update imaging SOP, due 2026-11-14
- [ ] K. Doyle: review recruitment flyer wording, due 2026-11-17

## Open questions carried forward
- Whether endpoint histology needs a second blinded reader

Every task gets a name and a date. Every decision gets a log entry. Notes are committed to the repository the same day, so the record never depends on one person's memory or laptop.

Step 8: Schedule the review cycle

Documentation decays. Put three recurring checks in the charter:

• Weekly, the protocol owner confirms the decision log has no entries affecting a stale protocol.
• Monthly, the project lead reads the last month of decisions and notes for contradictions.
• At each milestone, the whole team spends 30 minutes confirming the dictionary matches the actual data.

Step 9: Check that the system works

Run these checks monthly:

git log --oneline -10

Expected output:

e4f5g6h D-004: move imaging start to January
a1b2c3d D-003: exclude artifact grade >2 from imaging cohort
9i8j7k6 update README with new statistician contact

If the log shows bursts of commits days apart from the events they describe, or weeks of silence followed by a bulk dump, the system is drifting. Also grep for unfinished business:

grep -rn "TODO\|TBD" protocols/ data-docs/

Expected output when the system is healthy is either nothing or a short list with named owners. An unowned TODO is a decision nobody recorded.

Choosing Tools

The tool matters less than the habits, but the choice still has consequences. The table below summarizes the main options.

Plain text formats (Markdown, CSV, YAML) in a Git repository are the most durable option because they remain readable decades from now with any tool. Collaborative suites win on accessibility for community partners and clinicians who should not be asked to learn Git. Many teams run both, with Git as the source of truth and the suite used for drafts.

Tips That Make Documentation Stick

Write for the newest member. If the most junior person cannot follow a document, the document is written for insiders. Teams that involve patients, relatives, and community members as co-researchers find that accessible tasks and transparent communication are prerequisites for meaningful participation, not courtesies [2]. Plain language in shared documentation is the same principle applied to files.

Name a boundary spanner. In multi-partner research, the NSF-funded convergence projects recommend incorporating boundary spanners, people who move fluently between disciplines and communities, and building shared understanding deliberately rather than assuming it [3]. In documentation terms, this means one person who checks that the clinicians, the statisticians, and the community partners all understand the same document the same way.

Make contributions visible. When a co-researcher or junior trainee's input changes a protocol, record that in the decision entry. Visible use of contributions is one of the strongest facilitators of sustained participation identified in participatory oncology and palliative care research [2].

Standardize at the stages where errors multiply. Referral, assessment, planning, and review are where the hypodontia team placed its four proforma templates, and consistency improved at exactly those handoff points [1]. Find your handoff points, the moments a document passes between people, and put templates there.

Adapt rather than translate blindly. When two teams in five countries jointly adapted a maternal health instrument into Arabic, they documented a six-stage process (forward translation, synthesis, back translation, expert committee review, pre-final testing, and finalization) and added a country identifier to demographic items to distinguish collection sites [10]. The lesson for any multi-site team is that the adaptation process itself deserves a document, and site identifiers belong in the shared data structure from the start.

Plan for human limits. Teams that include peer researchers with disabilities report that successful collaboration requires open communication about needs, flexibility in timing, and institutional support, particularly when illness or accommodation needs affect availability [11]. Documentation systems should never assume uninterrupted full-time availability. Record decisions when they happen precisely because the person who made them may be away next week.

Address hierarchy in the documents themselves. Clinicians in outpatient eating disorder teams describe interprofessional collaboration as resting on dismantling systemic hierarchies to build trust, and on shared philosophies and values developed through joint education [12]. A decision log where any team member can add an entry, and where the rationale matters more than the rank of the author, is a small structural way to do this.

Common Mistakes and Limitations

These are the failures teams actually make, in rough order of frequency.

Mistake 1: Documentation as an afterthought. The most common failure is writing protocols and dictionaries after data collection, from memory. The field preparation phase recommended for cross-national cognitive assessment studies explicitly places creating documentation, interviewer training, and quality assurance planning before fieldwork [13]. Reverse the order and you will discover ambiguities after they have already corrupted the data.

Mistake 2: The document graveyard. Teams sometimes respond to an audit by generating volumes of records nobody reads. The E6(R3) consensus emphasizes proportionality, meaning documentation should match the risk and importance of what it records [6]. If a document has no reader and no trigger that updates it, cut it.

Mistake 3: The single custodian. If only one person knows where things are or how to commit changes, your documentation system has a bus factor of one. Rotate the facilitator role for meeting notes and have at least two people comfortable with the repository.

Mistake 4: Decisions by chat. Decisions made in a messaging thread and never copied to the log are invisible to anyone who joins later or whose thread scrolled away. The fix is a norm stated in the charter: a decision does not exist until it has a log entry.

Mistake 5: Ignoring onboarding and offboarding. Teams lose the most knowledge at membership transitions. The startup cost of this system, roughly two hours, pays for itself the first time a departing member leaves behind a readable record instead of an inscrutable drive.

Limitation 1: Overhead is real. Every entry in a decision log takes minutes. For a short exploratory project with two people, a full system may cost more than it returns. Scale the system to the project.

Limitation 2: Tooling does not fix culture. A Git repository full of terse commit messages and abandoned READMEs documents nothing. The behavioral research on team functioning is consistent on this point: what predicts performance is observable collaborative behavior, not the presence of a system [9]. If leadership does not model writing decisions down, no tool will compensate.

Limitation 3: Regulated settings have their own rules. If your project falls under clinical trial regulations, follow the applicable Good Clinical Practice requirements for source documentation rather than only the habits in this guide [6]. This guide covers general research practice, and individual projects with regulatory, legal, or biosafety obligations need review by the responsible institutional office.

Frequently Asked Questions

What counts as shared documentation for research teams?

Anything a teammate might need to continue your work without asking you: protocols, SOPs, the decision log, data dictionaries, meeting notes, the project charter, and records of who did what and when. Personal scratch notes and raw data files are generally not shared documentation until they are curated into one of those forms.

Where should our team store shared documentation?

In one place that every member can access and that records change history. For most teams this is a Git repository on a host like GitHub or an institutional GitLab. Teams with non-technical members often add a collaborative document suite for drafting, with approved versions moved into the repository.

How do we get busy team members to actually document?

Attach documentation to events that already happen, so it never competes for separate time. Write the decision log entry during the meeting where the decision is made, finalize meeting notes before leaving the room, and update the protocol as part of the same commit that changes the procedure. Teams also sustain participation better when contributions are visibly used, which documentation itself demonstrates [2].

What goes into a research project plan template?

At minimum: the project name and code, the lead and deputy, named roles with responsibilities, dated milestones, data sources, and a change control rule that routes every amendment to the decision log. The template shown in Step 2 above covers all of these and can be copied directly.

How much documentation is enough?

Enough that a qualified colleague could pick up the project and continue it, and no more. The current Good Clinical Practice revision explicitly favors proportionate documentation that avoids unnecessary burden [6]. A low-risk exploratory project needs a charter, a decision log, and a dictionary. A regulated trial needs far more, defined by its regulatory framework.

Should patients and community partners be part of shared documentation?

Yes, when they are team members. Participatory research projects find that meaningful involvement depends on transparent communication, accessible tasks, and visible use of contributions [2]. Write documentation in plain language, avoid unexplained technical jargon, and record community partners' inputs in the same decision log as everyone else's.

How do we handle documentation when someone joins or leaves the team?

Onboarding: give the new member the README, the charter, and the last month of decision log entries, which together provide the project's current state. Offboarding: run a handoff meeting where the departing member's owned documents are reassigned and their open tasks in the notes are confirmed or closed. Because the decision log is append-only, nothing they knew is lost if it was recorded at the time.

Do clinical trials need different documentation than basic research?

They need additional, regulator-defined documentation on top of the practices in this guide. The E6(R3) guideline clarifies expectations for source documentation, informed consent records, re-consenting, and delegation of tasks, with the aim of reducing administrative burden while protecting participants and data integrity [6]. Check with your institutional research office or sponsor about which requirements apply to your specific study.

Sources

1. Standardised proformas for the management of hypodontia patients: A new standard for clinical documentation.
2. Enabling meaningful participation and involvement in oncology and palliative care research: insights from two participatory research projects.
3. Navigating the practice of co-produced convergence research: Lessons from projects funded by NSF's Coastlines and People (CoPe) program.
4. A Qualitative Study of Team-Based Serious Illness Communication in ALS.
5. Organizational structures, coordination, and financing mechanisms among governmental emergency medical teams in the European region: a cross-case analysis.
6. ESMO and ASCO Consensus on Good Clinical Practice Guideline E6(R3): A Step Forward Towards Streamlining Clinical Research.
7. What do older adults think about involvement in health research through a citizen science lens? A situated qualitative study.
8. Automated self-service cohort selection for large-scale population sciences and observational research: The California Teachers Study researcher platform.
9. Concrete Behaviours Expected in Interdisciplinary Teams in Home Nursing Care Inspired by Buurtzorg: Qualitative Descriptive Study.
10. Navigating international academic collaboration: The Arabic translation and cultural adaptation of the Quality Maternal and Newborn Care Framework index.
11. Creating disability-inclusive research cultures: Opportunities, challenges, and recommendations for best practices in supporting peer researchers.
12. Collaboration in team outpatient eating disorder care: clinician's perspectives.
13. Recommended best practices for construct-centered adaptation of the Harmonized Cognitive Assessment Protocol.