Living Documentation in Git - Why Your SharePoint Word Docs Are Dead

You open SharePoint. Navigate to the project folder. Find “Solution Design v3 FINAL (2).docx” from 8 months ago. Half the integrations described don’t exist anymore. Three new ones aren’t documented. The ERD shows tables that were renamed in sprint 4.

Nobody updated it because nobody opens SharePoint to update a Word doc after a deployment. The doc was accurate the day it was written. It started dying the day after.

This is how most Dynamics 365 and Power Platform projects handle documentation. And it’s why most projects have no useful documentation at all.

Why Does Living Documentation in Git Beat SharePoint Word Docs?

Living documentation in git stays accurate because it versions alongside your code. SharePoint Word docs decay the moment they are saved, because they sit in a separate system that developers never touch during their normal workflow. Git-based docs get updated in the same pull request as the code change, reviewed by the same team, and tracked with the same history.

The Problem Is the Medium, Not the People

Your team isn’t lazy. The documentation process is broken.

Word docs in SharePoint have three fatal flaws:

1. They’re disconnected from the code. The solution ships from a git repo. The docs live in SharePoint. Nobody remembers to update both.
2. They don’t diff. When someone edits a Word doc, you can’t see what changed. Git shows you every line.
3. They’re invisible. Developers live in VS Code and git. They never open SharePoint unless someone sends them a link.

The Fix: Docs Live Next to Code

Put your documentation in the same git repo as your solution. Markdown files. Draw.io diagrams generated with Claude. Committed alongside the code.

your-project/
  /docs
    architecture.md
    erd.drawio
    integration-map.drawio
    data-migration.md
  /pcf
    ... your PCF source
  /solution
    ... your Dataverse solution

When a developer changes the schema, the ERD is right there in /docs. When someone adds an integration, the architecture diagram is in the same pull request. When a new team member joins, they clone the repo and have everything.

What Goes in /docs

Not everything. Just the stuff that matters and changes with the code:

What does NOT belong in git: meeting notes, project plans, status reports, contracts. Those belong in SharePoint or your PM tool. Git is for technical documentation that describes the system.

What a /docs Folder Looks Like in Practice

A typical Power Platform / D365 project repo following this pattern has a /docs folder with:

• architecture.md - ADRs (Architecture Decision Records) for every non-trivial choice
• ERD diagrams generated from Dataverse schema exports
• Integration maps showing system boundaries and data flows
• Configuration reference for JSON web resources

The discipline is straightforward: when an entity is added, the ERD gets updated in the same commit. When an integration is added, the architecture doc gets a new ADR. The docs are never more than one commit behind the code.

The figures below are illustrative diagrams generated from the Draw.io + Claude pipeline. They show the kinds of artifacts that belong in /docs for a typical Power Platform engagement, not measurements from a specific client engagement. Names, role labels, and counts are illustrative.

An end-to-end process diagram in the same /docs folder might capture all roles, flows, and components in one visual:

And the integration architecture showing how systems connect:

This approach pairs naturally with a governance repo where your standards, review checklists, and inventories also live as code.

How to Start

You don’t need to migrate everything at once. Pick one active project and do this:

Want more architecture and documentation patterns for Power Platform? Follow Alex on LinkedIn for weekly deep dives on building systems that document themselves.

The Comparison

What’s Next

This is the first post in a series on modern technical documentation for Power Platform and D365 projects. Next up: generating architecture diagrams with Draw.io and Claude - no Visio license required.

---

AZ365.ai - Azure and AI insights for architects building on Microsoft. Follow Alex on LinkedIn for architecture deep dives.