Fowel

What is Fowel?

Fowel is a GitHub App that reviews documentation changes in pull requests. It automatically posts inline comments and a summary review to help catch documentation issues—such as incorrect or outdated information, missing context, unclear writing, and broken examples—before the changes are merged.

The core purpose of Fowel is to add an automated documentation quality check alongside code review. It focuses on documentation files (including Markdown and MDX) and evaluates them across multiple quality factors so developers and reviewers can address problems earlier in the workflow.

Key Features

• GitHub App for per-PR documentation reviews: Fowel installs into GitHub repositories and runs reviews when documentation changes are included in a pull request.
• Automatic detection of documentation files: It detects Markdown, MDX, and other doc file types when they are modified in a PR, so reviewers don’t need to manually select what to check.
• Inline comments plus a summary review: Fowel posts detailed inline feedback and an overall review in the pull request so issues are visible during review.
• Documentation audit across multiple quality factors: It checks content accuracy, developer journey/onboarding flow, structure and information architecture, code samples (including runnability and error handling), clarity and style, and completeness.
• Supports automatic and manual reviews: The product includes both automated review runs and the ability to trigger reviews manually.

How to Use Fowel

1. Install the GitHub App: Add Fowel to your repository using the one-click install flow. The website states that this requires no configuration files, CI changes, or setup scripts.
2. Open a pull request with documentation changes: Push documentation updates to a branch and open a PR. Fowel detects documentation files automatically.
3. Review Fowel’s feedback in the PR: Review the inline comments and the summary posted by Fowel. Address issues (for example, outdated statements, missing error documentation, or broken code samples) and then update your PR as needed.

Use Cases

• Catching outdated procedures before merge: When a team updates API docs or guides, Fowel can flag contradictions and incorrect procedures that may not be caught by code review alone.
• Improving “time to first success” onboarding flows: Fowel evaluates the developer journey aspects of documentation, helping ensure users can reach a first API call without dropping off due to missing setup context.
• Validating reference documentation quality: For endpoints and API reference pages, Fowel checks that navigation, structure, naming, cross-linking, and the documentation’s completeness support developers looking up specific details.
• Detecting broken or misleading code samples: When examples are out of date or lack required error handling, Fowel validates runnability and syntax correctness so developers don’t copy/paste failing snippets.
• Reducing support burden caused by missing error/context docs: For documentation changes involving parameters, authentication notes, or error responses, Fowel focuses on whether the information is present and sufficiently clear to prevent “guessing” and repeated questions.

FAQ

Does Fowel review only Markdown files?
No. The page states it detects Markdown, MDX, and other doc files automatically when they are included in a pull request.

Where do the results show up?
Fowel posts inline comments and a summary review on the pull request.

Can reviews be triggered manually or only automatically?
Both are supported: the product includes automatic reviews and manual triggers.

What does Fowel check in documentation?
It performs a documentation audit across multiple quality factors, including content accuracy, developer journey, structure and information architecture, code samples, clarity and style, and completeness.

Does Fowel replace code review?
The site presents Fowel as an additional documentation quality check in the pull request workflow; it complements code review by focusing on documentation issues that code reviewers may not flag.

Alternatives

• Internal documentation review process (checklists or peer review): Teams can rely on human reviewers using quality checklists. Compared with Fowel, this is less automated and typically catches issues later.
• Static documentation linting/linters: Documentation lint tools can enforce formatting or basic correctness rules. They generally don’t provide the multi-factor documentation audit and contextual inline review described for Fowel.
• API documentation platforms with built-in validation: Tools that help generate API docs may reduce documentation drift for certain sources, but they may not review prose quality, onboarding flow, structure, and example runnability the way Fowel describes.
• General pull request review automation: Broad CI or PR automation can flag broken builds and tests, but it’s not specifically tailored to documentation accuracy, clarity, and completeness.