docs: Updates to Documentation #3
Conversation
There was a problem hiding this comment.
Summary of Changes
Hello @zeroasterisk, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!
This pull request significantly enhances the project's documentation by standardizing its formatting, expanding existing content, and introducing a new roadmap. The changes aim to improve the clarity, consistency, and comprehensiveness of the documentation, making it easier for users and contributors to understand the Agent Payments Protocol (AP2) and its future direction.
Highlights
- Prettier Configuration Update: The
.prettierrcfile has been updated to includeendOfLine,printWidth, andproseWrapoptions specifically for markdown files, ensuring consistent formatting across documentation. - Documentation Formatting and Readability: Numerous markdown files (
faq.md,index.md,partners.md, and several files underdocs/topics/) have been reformatted according to the updated Prettier rules, improving overall readability with consistent line breaks and bullet point styling. - New Roadmap Document: A new document,
docs/roadmap.md, has been added to outline the phased development approach for the Agent Payments Protocol (AP2), detailing current and future versions. - Enhanced FAQ and Conceptual Content: The
docs/faq.mdfile now includes two new frequently asked questions and a comprehensive glossary. Additionally,docs/topics/ap2-a2a-and-mcp.mdanddocs/topics/ap2-and-x402.mdhave received new informational blocks for better clarity. - Navigation Update: The
mkdocs.ymlconfiguration has been updated to incorporate the newly addedRoadmappage into the site's navigation structure.
Using Gemini Code Assist
The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.
Invoking Gemini
You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.
| Feature | Command | Description |
|---|---|---|
| Code Review | /gemini review |
Performs a code review for the current pull request in its current state. |
| Pull Request Summary | /gemini summary |
Provides a summary of the current pull request in its current state. |
| Comment | @gemini-code-assist | Responds in comments when explicitly tagged, both in pull request comments and review comments. |
| Help | /gemini help |
Displays a list of available commands. |
Customization
To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.
Limitations & Feedback
Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.
You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.
Footnotes
-
Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩
There was a problem hiding this comment.
Code Review
This pull request primarily introduces formatting changes across the documentation files, driven by new Prettier settings for Markdown. It also adds a new roadmap.md file and expands the faq.md with a glossary and new questions. My review focuses on content and formatting improvements for clarity. I've pointed out an incomplete sentence in the FAQ and suggested formatting improvements for the new roadmap to enhance readability. I also noted a minor typo.
docs/faq.md
Outdated
| - A primary objective is to provide supporting evidence that helps payment | ||
| networks establish accountability and liability principles. In a | ||
| dispute, the network adjudicator (e.g., Card Network) can receive the | ||
| user-signed. |
There was a problem hiding this comment.
This sentence appears to be incomplete, ending abruptly at 'user-signed.'. Please complete the sentence to clarify what the network adjudicator can receive.
There was a problem hiding this comment.
| **V0.1: (September 2025)** The initial specification focuses on establishing the | ||
| core architecture and enabling the most common use cases. Key features include: | ||
| Support for "pull" payment methods (e.g., credit/debit cards) Well-defined data | ||
| payloads to support transparent accountability based on the VC framework Support | ||
| for human-present scenarios Support for user and merchant-initiated step-up | ||
| challenges Detailed sequence diagram and reference implementation using A2A | ||
| protocol | ||
|
|
||
| **V1.x:** Subsequent versions will expand the protocol's capabilities based on | ||
| community feedback and evolving needs. Potential areas of focus include: Full | ||
| support for "push" payments and all payment methods (e.g., real-time bank | ||
| transfers, e-wallets etc.) Standardized flows for recurring payments and | ||
| subscriptions Support for human-not-present scenarios Detailed sequence diagrams | ||
| for MCP-based implementations | ||
|
|
||
| **Long-Term Vision:** Longer term, we plan the protocol to incorporate more | ||
| intelligence and flexibility, including: Native support for complex, | ||
| multi-merchant transaction topologies Support for real-time negotiations between | ||
| buyer and seller agents We believe that a collaborative approach is essential to |
There was a problem hiding this comment.
For better readability, the features and areas of focus under each version should be formatted as a bulleted list. This will make the roadmap easier to scan and understand.
**V0.1: (September 2025)** The initial specification focuses on establishing the
core architecture and enabling the most common use cases. Key features include:
- Support for "pull" payment methods (e.g., credit/debit cards)
- Well-defined data payloads to support transparent accountability based on the VC framework
- Support for human-present scenarios
- Support for user and merchant-initiated step-up challenges
- Detailed sequence diagram and reference implementation using A2A protocol
**V1.x:** Subsequent versions will expand the protocol's capabilities based on
community feedback and evolving needs. Potential areas of focus include:
- Full support for "push" payments and all payment methods (e.g., real-time bank transfers, e-wallets etc.)
- Standardized flows for recurring payments and subscriptions
- Support for human-not-present scenarios
- Detailed sequence diagrams for MCP-based implementations
**Long-Term Vision:** Longer term, we plan the protocol to incorporate more
intelligence and flexibility, including:
- Native support for complex, multi-merchant transaction topologies
- Support for real-time negotiations between buyer and seller agents
We believe that a collaborative approach is essential to| multi-merchant transaction topologies Support for real-time negotiations between | ||
| buyer and seller agents We believe that a collaborative approach is essential to | ||
| creating a protocol that is robust, secure, and meets the diverse needs of the | ||
| entire ecosystem. We actively seek feedback and critique on the github |
There was a problem hiding this comment.
There's a small typo here. For brand consistency, github should be capitalized to GitHub.
| entire ecosystem. We actively seek feedback and critique on the github | |
| entire ecosystem. We actively seek feedback and critique on the GitHub |
| "printWidth": 80, | ||
| "proseWrap": "always" |
There was a problem hiding this comment.
I recommend against these, it can improve readability of the source files, but it's difficult to maintain.
No description provided.