How to Contribute Documentation to OpenWork: A Complete Contributor's Guide

Fork the repository, create a docs/ branch, add or edit markdown files in the docs/ folder, and open a pull request against the dev branch to contribute documentation to OpenWork.

OpenWork is an open-source AI agent framework maintained by different-ai. Contributing documentation helps newcomers onboard faster and keeps the project accessible. This guide walks through the exact steps to add, improve, or correct documentation based on the repository's actual structure and contribution policies.

Understanding OpenWork's Documentation Structure

All user-facing documentation lives in the docs/ directory at the repository root. The project uses plain markdown files with GitHub-flavored syntax—no complex build pipeline required for basic contributions.

Key Files to Know Before Contributing

File	Purpose
README.md	Project overview and primary entry point for new users
CODE_OF_CONDUCT.md	Community behavior expectations for all contributors
SUPPORT.md	Guidance on getting help and filing issues
docs/	Directory containing all published documentation
packages/types/src/openwork-provider.ts	Example source file you may need to reference

Existing documentation examples include desktop-app-policies.md, extensions-manifest-foundation.md, and marketplace-capabilities-architecture.md. Review these to understand the established style and depth.

Step-by-Step Documentation Contribution Workflow

1. Fork and Clone the Repository

Start by creating your personal copy of the repository:

# Fork via GitHub UI, then clone your fork

git clone https://github.com/<your-username>/openwork.git
cd openwork

2. Create a Descriptive Branch

Branch naming should clearly indicate the documentation topic:

git checkout -b docs/your-topic-description

Good branch names: docs/add-cli-quickstart, docs/fix-typos-in-architecture, docs/update-installation-guide.

3. Add or Edit Documentation Files

Creating new documentation:

Create a file under docs/ with a clear, kebab-case filename:

cat <<EOF > docs/cli-quickstart.md

# OpenWork CLI Quick-Start

This guide shows how to install and run OpenWork from the command line.

## Prerequisites

- Node.js 18+
- pnpm

## Installation

[Install instructions](https://github.com/different-ai/openwork/blob/dev/README.md#install-with-your-ai-agent)

## Next Steps

See [OpenWorkProvider.ts](https://github.com/different-ai/openwork/blob/dev/packages/types/src/openwork-provider.ts) for the core provider interface.
EOF

Editing existing documentation:

Locate the target file in docs/ and modify directly. Preserve existing heading structure and link patterns.

4. Follow OpenWork's Documentation Style

• Use GitHub-flavored markdown for all formatting
• Keep headings logically nested (H1 → H2 → H3)
• Add a short front-matter comment for description if desired
• Use markdown links for internal references—never raw URLs
• Link to source files using absolute paths to the dev branch

5. Validate Your Changes (Optional)

While not required for pure documentation changes, running the test suite catches syntax errors:

# Install dependencies

pnpm install

# Run development server

pnpm dev

# Run tests to verify no regressions

pnpm test

6. Commit with a Conventional Message

Use the docs: prefix for all documentation commits:

git add docs/cli-quickstart.md
git commit -m "docs: add CLI quick-start guide"

7. Push and Open a Pull Request

git push origin docs/add-cli-quickstart

Then open a pull request against the dev branch of different-ai/openwork. Never target main directly.

8. Complete the PR Checklist

Your pull request description must include:

• A brief summary of the documentation change
• Relevant issue numbers (e.g., Closes #123)
• Confirmation that you have read the CODE_OF_CONDUCT.md and that your contribution follows it

9. Respond to Review Feedback

Maintainers may request edits or clarification. Push additional commits to your branch—the PR updates automatically.

Complete Contribution Example

# 1️⃣ Fork the repo on GitHub

# 2️⃣ Clone your fork locally

git clone https://github.com/<your-username>/openwork.git
cd openwork

# 3️⃣ Create a branch for the doc update

git checkout -b docs/add-cli-quickstart

# 4️⃣ Add a new markdown file

cat <<EOF > docs/cli-quickstart.md

# OpenWork CLI Quick-Start

This guide shows how to install and run OpenWork from the command line…

[Install instructions](https://github.com/different-ai/openwork/blob/dev/README.md#install-with-your-ai-agent)
EOF

# 5️⃣ Commit and push

git add docs/cli-quickstart.md
git commit -m "docs: add CLI quick-start guide"
git push origin docs/add-cli-quickstart

# 6️⃣ Open a PR on GitHub targeting the `dev` branch

Once merged, your documentation appears on the official docs site at https://openworklabs.com/docs.

Summary

• Documentation location: All user-facing docs live in the docs/ directory as *.md files
• Target branch: Always open pull requests against dev, never main
• Branch naming: Use docs/descriptive-topic format for clarity
• Style requirements: GitHub-flavored markdown, logical headings, markdown links only
• Source references: Link to exact files on the dev branch (e.g., packages/types/src/openwork-provider.ts)
• Commit convention: Prefix with docs: for all documentation changes
• PR requirements: Summary, issue references, and Code of Conduct acknowledgment

Frequently Asked Questions

What happens to my documentation after it's merged?

Merged documentation is automatically published to the official OpenWork docs site at https://openworklabs.com/docs. The site rebuilds from the docs/ directory on the dev branch.

Can I contribute documentation without coding skills?

Yes. OpenWork's documentation is plain markdown—no JavaScript, TypeScript, or framework knowledge required. You only need familiarity with GitHub's fork-and-pull workflow and basic markdown syntax.

How do I link to source code from documentation?

Use absolute URLs pointing to the dev branch with the exact file path. For example: [OpenWorkProvider.ts](https://github.com/different-ai/openwork/blob/dev/packages/types/src/openwork-provider.ts). This ensures links remain valid even as the repository evolves.

What if my documentation references a feature that doesn't exist yet?

Coordinate with maintainers by opening an issue first. Documentation for unreleased features should target the same branch as the feature code—typically dev. Include a note in the PR description explaining the dependency on other pending changes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}