Docs-as-Code Migration Readiness Template

1. Define the source of truth

Decide which system owns the accepted version of documentation after migration.

Area	Decision to make	Your answer
Canonical source	Where will the accepted version live?
Repository	Which repository holds documentation?
Branch	Which branch is authoritative?
Ownership	Who owns repository permissions?
Change path	How do UI edits enter Git?
Sync direction	Which changes can move both ways?

Readiness check

We know exactly which system is canonical
We know which branch is authoritative
We know who can merge documentation changes
We have tested both Git-to-platform and platform-to-Git changes

2. Map contribution workflows

Avoid forcing every contributor into the same interface. Map how each group works today and what must change.

Contributor	Current tool	Future tool	Review path	Owner
Technical writers
Engineers
SMEs / product
Support / CX
Localization

Questions to resolve

Which contributors need a visual editor instead of Git?
Which changes require a pull request?
Who reviews technical accuracy?
Who reviews clarity, structure, and user experience?
Can non-technical contributors participate without learning branch mechanics?

3. Set Git operating rules

Docs-as-code needs an operating model. Capture the rules before rollout, not after conflicts appear.

Rule	Decision	Your policy
Branch strategy	Which branches can contain docs?
PR requirement	Which documentation changes require a PR?
Approvals	How many approvals are required, and from whom?
Merge ownership	Who can merge documentation PRs?
Conflict handling	Where do conflicts appear, and who resolves them?
Naming conventions	How are branches, commits, and PRs named?
Permissions	Do documentation contributors need new repository access?
Audit trail	What history needs to be retained?

4. Identify dependent systems

Git may already sit between documentation and teams or systems outside the writing function.

Dependent systems to map

Localization — Does translation pull/push content through Git?

Must remain unchangedOwner:

OpenAPI / Swagger — Is the API specification engineering-owned?

Must remain unchangedOwner:

CI/CD — Do builds or deploys depend on docs in the repository?

Must remain unchangedOwner:

Release management — Do docs follow release branches or software releases?

Must remain unchangedOwner:

Automation — Do scripts or bots read/write documentation files?

Must remain unchangedOwner:

Search / indexing — Does another system ingest published output?

Must remain unchangedOwner:

Support / product — Do internal teams depend on specific publishing locations?

Must remain unchangedOwner:

5. Map publishing and release

Publish trigger — What causes docs to publish: merge, manual action, schedule, or release?

Your answer:

Preview — Can writers preview before publishing?

Your answer:

Release cadence — Do docs publish with product releases or independently?

Your answer:

Rollback — How do you restore the last accepted version?

Your answer:

Environments — Do you need staging, preview, and production environments?

Your answer:

Permissions — Who can publish to production?

Your answer:

6. Inventory what must survive the migration

For MadCap Flare teams, inventory more than topics. Reuse, conditions, links, outputs, and localization assets can create hidden migration work.

Topics / pages
Snippets / reusable content
Variables
Conditional content
Cross-references and links
Images and media
Metadata / tags
Navigation / TOC structure
OpenAPI / Swagger references
Localization files / workflows
PDF or other output targets
Redirects / URLs
Search configuration
Custom scripts / integrations

For each checked asset, record:

Must migrate?Test method:Owner:

7. Run a migration pilot

Choose a representative sample that exercises the difficult parts of the workflow, not just the easiest pages.

Pilot scope — Which docs or product area will be tested?

Content sample — Does it include reuse, conditions, links, API content, and media?

Writer test — Can a writer edit, review, and submit a change?

Result / notes:

Engineer test — Can an engineer update via Git and see the change reflected?

Result / notes:

Localization test — Can translated content move through the expected workflow?

Result / notes:

Publishing test — Can the team preview, publish, and roll back?

Result / notes:

Conflict test — What happens when both sides edit the same content?

Result / notes:

8. Define success, rollback, and ownership

Success criteria

Time from doc change to approval

Baseline:Target:How measured:

Engineering review participation

Baseline:Target:How measured:

Publishing errors / failed builds

Baseline:Target:How measured:

Localization turnaround

Baseline:Target:How measured:

Writer time spent on Git mechanics

Baseline:Target:How measured:

Broken links / migration defects

Baseline:Target:How measured: