Uniswap / Uniswap/docs

[Docs] Missing cross-links and structural gaps in developers.uniswap.org

Open
#1,130 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
MDX
Stars
380
Forks
645
Avg merge
21m
Merged PRs (30d)
1

Description

Summary

During a navigation audit of developers.uniswap.org/docs (May 2026), I found several structural issues that block developer onboarding.

Structural Gaps

  1. No inline API reference — API docs live on a separate domain (api-docs.uniswap.org) with no integrated search or navigation inside the main developer portal.
  2. Missing v3 → v4 migration guide — No comparative guide for devs migrating existing integrations.
  3. Hook guides lack production patterns — The Counter Hook example is too basic; intermediate patterns (dynamic fees, oracles, limit orders) and end-to-end deployment guides (address derivation, bit flags, CREATE2) are missing.
  4. No docs bug-reporting channel — The official feedback Google Form collects role/experience data but has no field to report broken links or documentation errors.

Suggested Fixes

  • Integrate API reference pages directly into developers.uniswap.org/docs/api/reference.
  • Add a [Docs Bug] issue template to this repo.
  • Provide a "Report a docs issue" link in the portal footer.

Environment

  • Date tested: 2026-05-06

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the navigation audit of developers.uniswap.org/docs and compare the main portal with api-docs.uniswap.org. Review the proposed API reference path, migration and hook-guide gaps, footer feedback link, and [Docs Bug] issue template separately. The work is done only when a maintainer narrows these findings into specific documentation tasks and acceptance criteria.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.