Contribute to the Base Account Docs

This guide is intended for all contributors who are adding new features, content, or making updates to the Base Account documentation. Following these guidelines ensures consistency and maintains the documentation structure, making it easier for developers to find information.

Why Documentation is Important

Good documentation significantly accelerates developer adoption. Focus on creating content that helps developers understand and implement Base Account features efficiently, while maintaining the documentation’s structural integrity.

Documentation Structure Guidelines

Core Principle: Maintain Existing Structure

The Base Account documentation is organized into the following main sections:

1. Introduction
2. Quickstart
3. Guides
4. Framework Integrations
5. Reference
6. More
7. Basenames
8. Contribute

Do not create new top-level sections

All new content must fit within these existing sections.

Section Purpose and Content Placement

When adding new content, determine the appropriate section based on the following criteria:

Introduction

• High-level explanatory content about what Base Account is and its core value proposition
• Update only when there are fundamental changes to the product positioning or capabilities

Quickstart

• End-to-end guides for getting developers up and running quickly
• Should remain focused and concise
• Covers different integration paths (web, web with React, mobile)

Guides

• Step-by-step tutorials for specific tasks and implementation scenarios
• Includes guides for authentication, payments, and UX improvements
• Covers features like:
  • User authentication
  • Accepting payments and recurring payments
  • Batch transactions
  • Paymasters and gas sponsorship
  • Sub Accounts
  • Spend Permissions
  • Magic Spend
• Name guides clearly with action-oriented titles (e.g., “Accept Payments” rather than “Payments Guide”)

Framework Integrations

• Detailed integration guides for specific frameworks and libraries
• Subsections organized by framework:
  • Wagmi/Viem: Setup, batch transactions, Basenames, and other use cases
  • Privy: Setup, authentication, wallet actions, and sub-accounts
  • CDP: Coinbase Developer Platform integration
  • RainbowKit: Integration with RainbowKit
• Each framework section should cover setup and common use cases

Reference

• Comprehensive technical documentation of APIs, methods, components, and configurations
• Structured reference material rather than tutorial content
• Include parameter descriptions, return values, and usage examples
• Organized by component:
  • Account SDK: Core functions, Spend Permission utilities, Base Pay, subscriptions, and Prolink utilities
  • Provider: Methods (RPC methods like wallet_connect, wallet_sendCalls, etc.) and Capabilities
  • UI Elements: Base Pay Button, Sign In With Base Button, brand guidelines
  • Onchain Contracts: Spend permissions, smart wallet, and Basenames contracts

More

• Additional resources and supplementary documentation
• Troubleshooting guides (popups, gas usage, unsupported calls, simulations, wallet library support)
• Base Gasless Campaign information
• Telemetry information
• Migration guides

Basenames

• Documentation specific to Basenames functionality
• FAQs and common questions
• Basename transfer documentation

Contribute

• Information for contributors to the Base Account project
• Security and bug bounty information
• Update when contribution processes change

Avoiding Subsection Proliferation

• For Guides: Keep all guides at the same level under the Guides section
• For Reference: Organize by component or feature, not by use case
• For Framework Integrations: Keep framework-specific content within its respective framework subsection
• When tempted to add a new subsection, consider if the content could be reorganized to fit existing sections
• Use cross-referencing between related content rather than creating new organizational structures

Documentation Style Guidelines

Writing Style

1. Be concise: Use simple, direct language. Avoid unnecessary words.
2. Consistency: Maintain consistent terminology throughout documentation.
3. Persona-focused: Think about the persona of the reader and write accordingly.
4. Happy Path: Focus on the happy path, but don’t forget to mention the alternative paths.
5. AI-friendly: Write in a way that is easy for AI to understand and follow.

Make sure to review any AI generated content

If you use AI to generate content:

• Make sure to review it carefully before submission.
• Make sure that the content follows the guidelines in this document.
• Make sure that the content is easy for AI to understand and follow.

AI-friendly Writing Tips

• Make sure you use explicit language in your file names, headings, and content.
• Make active linking references to the relevant guides and examples.
• Use bulleted lists for steps or options.
• Explicitly name and reference the libraries you are using.
• Use code blocks to highlight code.
• Use semantic urls that make sense even without context. Avoid abbreviations.

Think like a Large Language Model

When writing documentation, think about how a Large Language Model would understand the content.

You should continuously ask yourself:

• “Would a Large Language Model be able to understand this content?”
• “Would a Large Language Model be able to follow this content?”
• “Would a Large Language Model be able to use this content?”

If you can’t answer yes to all of these questions, you need to rewrite the content.

Formatting

1. Markdown usage:

   • Use proper heading hierarchy (# for main titles, ## for section headings, etc.)
   • Use code blocks with language specification (```javascript)
   • Use tables for parameter references
   • Use bulleted lists for steps or options

2. Code examples:

   • Include complete, working code examples
   • Comment code thoroughly
   • Follow the project’s coding style guide

Abbreviations and Terminology

1. First reference: The first time you use an abbreviation or technical term, spell it out followed by the abbreviation in parentheses. Example: “Account Abstraction (AA)”
2. Consistency: Use the same term for the same concept throughout the documentation
3. Technical Reference: Keep the guides and examples to a minimal size. Put the comprehensive technical details in the Technical Reference section.

Review Checklist Before Submission

• Content fits within existing structure
• No new top-level sections created
• Minimal subsection creation
• Consistent terminology used throughout
• Abbreviations properly introduced
• Code examples are complete and functional
• Cross-references to related documentation added
• Documentation follows style guidelines
• Documentation is written in a way that is easy for AI to understand and follow

Submission Process

1. Create a documentation Pull Request (PR) to the repository with your changes
2. Ensure your PR includes updates to all relevant sections and respects the instructions in this guide
3. Request review from the documentation team
4. Address feedback and make necessary revisions
5. Once approved, the PR will be merged and published