A Markdown and Git workflow for product documentation

Choose where changes begin

A repository can be the starting point for a release’s documentation, while a visual editor handles reader-facing refinements. Problems arise when both copies change independently and nobody knows which one should win.

Agree on a rule for each collection. For example, keep release-specific technical instructions in the repository and use the editor for support answers that are not maintained in Git. If the same article can change in both places, require an explicit review before importing the next revision.

Keep files understandable outside the original tool

Give each Markdown file a focused purpose and a clear title. Use predictable folders for the supported product or collection. Keep an inventory of metadata, images and links that must survive the import, because Markdown text alone does not carry every publishing rule.

Try opening a source file in a plain text editor. A future author should identify the question, steps and success check without relying on an undocumented extension. Where your publishing tool uses a specific video or callout syntax, document that convention for the team.

Use the ClearWay Docs reviewed import workflow

On Core and Pro, ClearWay Docs can preview Markdown from a GitHub or GitLab repository and import the reviewed snapshot. Its import workflow checks for conflicts with newer web edits instead of silently treating the repository as the winner.

The current integration is repository-to-knowledge-base import. It does not write visual-editor changes back to Git, open pull requests or automatically ingest every repository push. Plan a deliberate preview and import step in the release workflow. Choose another integration requirement explicitly if you need automatic two-way synchronization.

• Check ClearWay Docs Git and import capabilities

Review the result as a customer would read it

After importing, check code fences, tables, heading order, image references and links to other articles. A file can parse successfully while still being confusing or pointing to an old repository-relative path.

Use the published audience and product version as part of the check. Keep a draft while you resolve conflicts or incomplete content. In ClearWay Docs, editing a published article’s draft does not replace the live revision until it is republished.

Give your agent a bounded maintenance task

An agent can identify which articles a product change affects or prepare a draft through MCP. Give it the released behavior and ask it to identify uncertain details. Keep its task limited to documentation until you deliberately grant another responsibility.

If the source lives in Git, ask the agent to update that source under your chosen review process. If ClearWay Docs owns the article, ask it to save a draft there. Making ownership explicit prevents the agent from producing two competing versions of the answer.

• Follow the agent drafting and review workflow

Common questions