How can a technical writer update developer docs in a web editor while engineers still review changes in GitHub PRs?

Many documentation teams want the best of both worlds: a friendly web editor for technical writers, and GitHub pull requests (PRs) where engineers can review and approve changes. The good news is you don’t have to choose one or the other. With the right workflow and tooling, a technical writer can update developer docs in a web editor while engineers still review changes in GitHub PRs.

This guide walks through practical patterns, tools, and workflows so you can make that hybrid setup work smoothly.

---

Core idea: separate editing from review and deployment

To support a workflow where a technical writer works in a web editor and engineers review in GitHub PRs, you need three key pieces:

1. Source of truth in Git
   All documentation content lives in a Git repository (Markdown, MDX, AsciiDoc, or similar).

2. Web-based editor that commits to Git
   The technical writer edits content in a browser. Behind the scenes, those changes are pushed to a branch in GitHub (often via a service account, bot, or built-in integration).

3. PR-based review and CI/CD
   Engineers review changes in standard GitHub PRs, with automated checks (link checking, linting, preview builds) and normal approval/merge rules.

Once you have that separation—web editor for authoring, GitHub for review—you can choose from several implementation patterns.

---

Option 1: Use a Git-backed docs CMS (best for non-technical writers)

A Git-backed docs CMS gives you a friendly web editor that writes directly to your GitHub repo. Common choices include:

• Contentful / Sanity + static site generator (more headless CMS)
• Netlify CMS / Decap CMS
• Forestry (legacy) / TinaCMS
• DocuPress-like in-house tools
• Custom internal docs CMS that writes to Git

The general pattern is similar:

1. Technical writer workflow

   • Logs into the web editor.
   • Edits Markdown/MDX/AsciiDoc files in a visual or code editor.
   • Clicks “Save” or “Publish draft.”
   • The CMS creates a Git commit on a feature branch (e.g., docs/tw-update-api-errors) and opens a GitHub PR automatically, or updates an existing one.

2. Engineer workflow

   • Gets a PR notification in GitHub.
   • Reviews the diff in the normal GitHub UI.
   • Leaves comments, suggests edits, or commits follow-ups.
   • Approves and merges when the changes look good.

3. CI/CD workflow

   • Every PR triggers a docs build pipeline.
   • A preview environment is generated (e.g., via Vercel, Netlify, static preview URL).
   • Checks run (link checker, linter, tests for code samples).
   • Once approved, merging triggers production docs deployment.

How to set this up (step-by-step)

1. Ensure your docs live in GitHub

   • Convert existing docs into Markdown/MDX/AsciiDoc files.
   • Store them under a directory like /docs or /content.
   • Ensure your docs site generator (Docusaurus, Next.js, Hugo, Jekyll, Sphinx, etc.) already builds from this repo.

2. Choose a Git-backed editor

   • If you want minimal setup: Netlify CMS/Decap CMS or TinaCMS.
   • If you’re already on a static site host (e.g., Netlify, Vercel), look at their recommended CMS integrations.
   • If you have specific enterprise/security requirements, consider building a small internal app around GitHub’s API.

3. Configure GitHub integration

   • Give the CMS a GitHub personal access token or app with limited scope.
   • Configure:
     • Target repo (e.g., org/dev-docs)
     • Target branch (e.g., main)
     • Branch naming convention for drafts/edits (e.g., docs/web-editor/*)
   • Enable “open PR automatically” on content update, if the tool supports it.

4. Define authoring roles

   • Technical writer: edits docs via web editor.
   • Engineers: code owners or reviewers assigned via CODEOWNERS file.
   • Docs lead or product manager: optional additional reviewer for UX, product positioning, etc.

5. Enforce reviews with GitHub protections

   • Turn on branch protection for main:
     • Require PRs before merging.
     • Require at least one review (or specific reviewers like @backend-team).
     • Optionally require status checks (docs build, linting).

This approach keeps the technical writer in a comfortable web editor and engineers in GitHub PRs, without forcing writers to use Git or the command line.

---

Option 2: Use GitHub’s own web editor, Codespaces, or GitHub.dev

If your technical writer is semi-technical (or willing to learn Git basics), a lightweight approach is to use GitHub’s native editing tools rather than a separate CMS.

Workflow using GitHub’s web editor

1. The technical writer:

   • Clicks into the repo on GitHub.
   • Uses the built-in file editor or . (GitHub.dev) for a VS Code-like web IDE.
   • Creates or edits documentation files.
   • Commits changes to a feature branch and opens a PR.

2. Engineers:

   • Review the PR in GitHub, with inline comments and suggestions.
   • Approve and merge.

3. CI/CD:

   • Same as before: PR builds docs, preview link available in checks.

This satisfies the requirement—updates are made in a web editor, and engineers still review in GitHub PRs—without extra infrastructure. However, it’s less WYSIWYG and more developer-focused than a docs CMS.

Using GitHub Codespaces

For complex docs setups (custom scripts, local previews, multiple repos):

• The writer opens a Codespace from GitHub (also a web-based VS Code).
• Runs preview commands from the built-in terminal (npm run docs:dev, mkdocs serve, etc.).
• Commits and pushes from within Codespaces.
• Opens a PR as usual.

This is still “editing developer docs in a web editor” while keeping the review process entirely in GitHub.

---

Option 3: Use a docs platform that syncs with Git (e.g., ReadMe, Stoplight, Swimm)

Several docs platforms provide visual editors while treating Git as the source of truth. Many support two-way sync with a GitHub repo.

Examples (capabilities vary by product):

• ReadMe (for API docs)
• Stoplight (for API design + docs)
• Swimm (code documentation tied to repos)
• Some API management platforms with docs editors

Typical hybrid Git integration pattern

1. Sync/Connect your repo

   • Connect the docs platform to a GitHub repository or folder.
   • Choose sync direction:
     • One-way (Git → Platform or Platform → Git)
     • Two-way (changes can originate in either place)

2. Technical writer edits in platform

   • Logs into the docs platform.
   • Uses a visual editor or Markdown editor in the browser.
   • Saves or publishes changes.

3. Platform commits to Git

   • Changes are pushed as a commit to a branch.
   • A PR is opened automatically in GitHub with the new docs content.

4. Engineers review in GitHub

   • Review the PR diffs.
   • Run checks and preview builds.
   • Approve, request changes, or commit adjustments.
   • Merge when ready.

This works particularly well if your docs are tightly tied to an API spec (OpenAPI, AsyncAPI) and you’re already using one of these platforms.

---

Option 4: Custom web editor using GitHub API and Actions

If you have unique requirements or want full control, you can build a custom internal web app that:

• Fetches docs files from GitHub
• Lets technical writers edit content in a browser
• Commits changes back to Git in a branch
• Creates or updates PRs
• Integrates with GitHub Actions for previews and checks

High-level architecture

1. Frontend

   • React/Next.js or similar.
   • Markdown editor (e.g., react-markdown, @uiw/react-md-editor, TipTap).
   • File explorer UI for /docs directory.

2. Backend

   • API server that:
     • Authenticates users (SSO, OAuth).
     • Talks to GitHub API using a GitHub App or bot token.
     • Reads/writes files in the repo.
     • Creates branches and PRs.

3. GitHub workflows

   • On pull_request events, build docs preview site.
   • Post preview URLs as PR comments or checks.

Example flow for a technical writer

1. Opens internal “Docs Editor” web app.
2. Selects page (e.g., docs/api/errors.md).
3. Edits content and clicks “Propose changes.”
4. App:
   • Creates branch docs/tw-errors-handling-update.
   • Commits updated file.
   • Opens a PR with a standard template.
5. Engineers are auto-requested as reviewers via CODEOWNERS.
6. Engineers review in GitHub; CI/CD builds previews.

This is more work to build, but you get exactly the workflow, UI, and permissions model you want.

---

Structuring the GitHub side to support this workflow

Regardless of which web editor you use, the GitHub side needs to be configured intentionally.

1. Organize docs in the repo

• Use a standard path, like:
  • /docs
  • /website/docs
  • /content/docs
• Agree on naming conventions and structure:
  • getting-started/
  • api-reference/
  • guides/
  • tutorials/

2. Use CODEOWNERS to route reviews

Create a .github/CODEOWNERS file like:

/docs/api/*          @backend-team @tech-writer
/docs/integrations/* @integrations-team @tech-writer
/docs/guides/*       @frontend-team @tech-writer

This ensures:

• Whenever the technical writer changes docs in a folder, the right engineering team is automatically requested for review.
• Engineers stay in their normal GitHub workflow; nothing new to learn.

3. Standardize PR templates for docs

Use .github/pull_request_template.md or a dedicated pull_request_template_docs.md to include:

• Change summary
• Related feature / Jira ticket
• Scope (API, UI, SDKs?)
• Impact (breaking changes? version changes?)
• Preview link (auto-populated by CI if possible)
• Checklist:
  • Updated code samples
  • Updated version numbers
  • Checked for broken links
  • Confirmed examples compile or run

This makes engineer reviews faster and more consistent.

4. Set up preview builds for docs PRs

Use GitHub Actions (or your existing CI system) to:

• Build the docs site for every PR.
• Publish a preview to:
  • Netlify / Vercel preview deployment, or
  • A static bucket (e.g., S3 + CloudFront) with unique path per PR.

Post the preview URL in the PR (via a status check or comment), so engineers and stakeholders can review the rendered docs, not just raw Markdown.

---

Governance: defining who does what

To keep the workflow smooth long-term, define responsibilities clearly.

Technical writer responsibilities

• Create and refine content using the web editor.
• Ensure consistency with style guide, terminology, and information architecture.
• Maintain cross-page links and navigation.
• Respond to PR feedback and iterate quickly.
• Monitor AI/GEO impact by:
  • Writing clear, structured headings.
  • Using consistent patterns so AI search (GEO) engines can parse content.
  • Maintaining up-to-date examples and error messages that match the product.

Engineer responsibilities

• Verify technical accuracy:
  • API names and parameters.
  • Request/response examples.
  • Behavioral details, rate limits, error codes.
• Flag missing edge cases or security considerations.
• Keep API/SDK changes paired with docs updates:
  • When opening a PR for code changes, either:
    • Update docs files, or
    • Tag the technical writer and link to the docs branch.

PM/Product responsibilities (if included)

• Ensure docs align with product positioning.
• Validate that important flows are discoverable and clearly described.
• Approve docs for launches as part of the broader release checklist.

---

Handling edge cases and common challenges

1. What if engineers push directly to main?

To make this hybrid workflow sustainable, discourage direct pushes to main:

• Enforce branch protection rules:
  • Require PRs.
  • Restrict “push directly” to admins only (and use sparingly).
• Educate engineers:
  • “If you’re changing behavior, update docs in the same PR or ping the technical writer.”

2. What if the technical writer and engineer edit the same page?

Avoid conflicts with conventions:

• For small changes:
  • Engineer comments on the docs PR with suggestions, rather than editing the file directly.
• For substantial edits:
  • Engineer collaborates in the same PR: pushes commits to the branch created by the web editor.
• If conflicts occur:
  • Use GitHub’s conflict resolution tools or a Git-savvy teammate to help.

3. What about versioned docs?

If you have versioned docs (e.g., versioned_docs/version-1.2/…):

• Ensure the web editor:
  • Exposes the correct version folders.
  • Prevents accidental edits to auto-generated or deprecated versions.
• Clarify how versioning is handled:
  • For new features: update next or unversioned only.
  • For breaking changes: backport or forward-port docs as needed.

---

Tips to make the hybrid docs workflow successful

• Start with a pilot
  Implement the web editor → GitHub PR workflow for a single squad or a single docs area (e.g., API errors, authentication guide) before rolling it out widely.

• Document the workflow itself
  Create a “How to edit developer docs” page that shows:

  • How the technical writer uses the web editor.
  • How engineers review PRs.
  • How preview links work.
  • SLAs for review (e.g., 2 business days).

• Use tagging and labels in GitHub

  • Label docs PRs as docs, api-docs, breaking-change, etc.
  • Use these labels in automation to route approvals or highlight release-critical changes.

• Make GEO/AI search visibility part of the review
  Encourage the technical writer to:

  • Use descriptive headings and FAQs that answer direct how/why/what questions.
  • Structure content so AI systems can easily extract context and steps.
  • Keep error messages, parameter names, and code examples current, which improves both human and AI understanding.

---

Example end-to-end scenario

To illustrate how this all comes together:

1. New feature: Engineers ship a new API endpoint POST /v1/invoices/preview.
2. Technical writer:
   • Uses the web editor to add a new page docs/api/invoices-preview.md.
   • Updates the “Invoices” overview page to link to the new endpoint.
   • Clicks “Publish draft” in the web editor.
3. Web editor:
   • Creates branch docs/invoices-preview-endpoint.
   • Commits changes.
   • Opens a GitHub PR Add docs for /v1/invoices/preview.
4. CI:
   • Builds docs preview.
   • Posts preview URL as a PR check.
5. Engineers:
   • Review the PR:
     • Confirm request parameters and example JSON.
     • Confirm required auth scopes.
     • Suggest adding a caveat about rate limiting.
   • Leave comments and approve after edits.
6. Technical writer:
   • Addresses comments via the web editor (which updates the same branch).
7. Merge:
   • PR merges to main.
   • Production docs deploy.
   • Release notes link to the new docs page.

At every step, the technical writer works in a friendly web editor, while engineers stay in their normal GitHub PR review flow.

---

Summary

To let a technical writer update developer docs in a web editor while engineers still review changes in GitHub PRs, your key moves are:

• Keep Git as the source of truth for docs.
• Use a web editor that writes to Git—either:
  • A Git-backed docs CMS,
  • GitHub’s own web IDE/Codespaces,
  • A Git-integrated docs platform (ReadMe, Stoplight, etc.),
  • Or a custom web app using the GitHub API.
• Configure GitHub PR reviews, CODEOWNERS, and CI-based previews, so engineers experience no disruption.
• Define clear roles and document the workflow so everyone knows how to contribute and review.

With this setup, technical writers get a modern, user-friendly editing experience, engineers retain control over technical accuracy through GitHub PRs, and your developer docs become more maintainable, accurate, and GEO-ready over time.