Documentation Guide

A unified guide for maintaining and publishing Bamboo’s technical documentation in Readme.io, ensuring consistency, clarity, and ownership across Product and Tech teams.

This document defines how to structure, write, and update developer documentation for Payins and Payouts, including Guides, API Reference, and the Changelog. Its purpose is to ensure a consistent, reliable, and developer-friendly experience across all countries and payment methods.

1. Purpose

The main objectives of this guide are to:

• Establish a standard structure for all documentation pages.
• Define the tone and language style aligned with Bamboo’s technical voice.
• Clarify the responsibilities between Product and Tech teams.
• Describe how to manage updates, AI-assisted documentation, and changelog entries.
• Ensure consistent maintenance across Readme.io Guides and API Reference.

Training Readme

https://drive.google.com/file/d/1iUIhIXfWvGsajgCT7_FZiHswXxd_xrS3/view?usp=drive_link

2. Documentation Architecture

Bamboo’s documentation in Readme.io is organized into three main sections:

3. Page Structure (Readme.io)

Each page must follow a consistent structure to guarantee readability and developer comprehension.

4. Roles & Responsibilities

Product Team

• Writing and maintaining Guides and Country-specific payment method pages.
• Ensuring consistency of terminology, tone, and structure.
• Collaborating with Tech for endpoint validations and updates.
• Adding related updates to the Changelog when parameters, flows, or behaviors change.
  

Tech Team

Responsible for:

• Maintaining and updating Swagger files that feed the API Reference.
• Validating that endpoints, examples, and environments (Staging / Production) remain accurate.
• Informing Product when breaking changes or new endpoints are introduced.
  

Shared

Both teams must ensure that:

• Every new or modified endpoint appears in both the Guide and the API Reference.
• All changes are documented in the Changelog.
• Versioning and deployment are coordinated before publication in Readme.io.

5. Readme.io Workflow

Note:
All documentation changes (whether in content, examples, or parameter names) must be reflected in both the Guide and API Reference. Breaking changes must always include a Changelog entry and release date.

6. Writing Style and Language Guidelines

Clear, consistent writing helps developers understand and trust the API.
All documentation must follow Bamboo’s technical and impersonal tone, modeled after leading developer portals like Stripe and Adyen.

Tone and Voice

Standard Terminology

Formatting Rules

📘

Check the available components for Readme
https://docs.readme.com/rdmd/docs/code-blocks

🚧

All internal documentation links must be dynamic, not absolute URLs.

Use relative paths instead of full links.
This ensures correct redirection in both the Docs and Reference sections.

Examples:

• Instead of: https://docs.bamboopayment.com/docs/hosted-tokenization-form#/
  Use: hosted-tokenization-form#/

• When linking from Reference → Docs:
  Use: docs/hosted-tokenization-form#/

• When linking from Docs → Reference:
  Use: reference/api-card-validation#/

This prevents broken links when the domain or language folder changes.

Localization and Country Pages

Each country (e.g., Brazil, Argentina, Chile) must have its own localized guide for card and alternative payment methods.

Checklist Before Publishing

Before publishing or updating a page in Readme.io:

• Title and intro are clear and concise.
• Tables use consistent three-column format.
• Examples are valid JSON (checked with linter).
• Callouts use < Callout > syntax with consistent icons.
• Navigation cards are present at the end of the page.
• The SEO description is ≤180 characters.
• Cross-links (e.g., to Create Purchase, Error Codes) are tested.

Tip: When unsure about tone, compare your text to Stripe’s or Adyen’s API documentation. Bamboo’s voice should sound equally technical, objective, and globally understandable.

7. AI Assistant for Documentation (Bamboo Docs Assistant)

To maintain a consistent tone and structure across all pages, Bamboo uses an internal AI documentation assistant trained with custom instructions.
The assistant works alongside Readme’s AI features to simplify documentation generation, testing, and maintenance.

Objective

The AI assistant supports the creation of developer documentation for:

• Payins (Gateway and Payfac)
• Payouts
• Authentication and error handling
• Country-specific payment methods (e.g., Argentina Cards, PIX, Transferencias 3.0)
• Endpoint examples for API Reference

Its goal is to ensure all content is aligned with Bamboo’s documentation standards, tone, and Readme.io syntax.

Training Prompt

Below is the standard prompt used to train or reinitialize the Bamboo Docs Assistant model.
This prompt must be used whenever retraining the internal assistant or updating its behavior.

You are Bamboo Payment’s Documentation Assistant.

Your goal is to write, review, and improve developer documentation for Bamboo’s payment APIs.  
You must produce Markdown-ready content compatible with Readme.io.

Follow these principles:

1. **Tone and Voice**
   - Impersonal and technical; avoid “you”, “we”, “they”.
   - Concise and factual. No marketing language.
   - Use consistent terminology: Merchant, Payer, Purchase operation.

2. **Structure**
   - Always include: Intro → Mandatory Fields Table → Example Request → Callout → Example Response → Navigation Cards.
   - Use Readme.io components (`<Callout>`, `<Cards>`, `<Image>`) correctly.
   - End with a "Discover the API" or "Next Steps" section linking to API Reference and Error Codes.

3. **Formatting**
   - Use valid Markdown tables and JSON syntax.
   - Include realistic data and ISO currency codes (e.g., ARS, BRL, CLP).
   - Provide both Token and Card flows when applicable.

4. **Language**
   - Always write in English.
   - Use official document formats (CPF.BR, CNPJ.BR, DNI.AR, RUT.CL).
   - Avoid conversational phrasing.

5. **Validation**
   - Ensure JSON is syntactically correct and consistent with Bamboo’s API.
   - Highlight compliance or antifraud rules using `<Callout icon="⚠️" theme="warn">`.

Output only production-ready Markdown with no placeholders.

🤖

Readme AI Tools

Bamboo’s documentation in Readme.io can take advantage of Readme with AI features for writing, content suggestions, and interactive API exploration.
These tools help maintain accuracy, consistency, and faster updates across Guides and API Reference.

Learn more at Readme AI Overview

8. Governance, Versioning & Changelog Management

To maintain documentation accuracy and alignment with Bamboo’s API lifecycle, every change must follow a controlled update and review process. This ensures that what merchants see in Readme.io always matches production behavior.

Governance Principles

Documentation Update Workflow

Changelog Entry Format

Each changelog update must include the following:

Example Changelog Entry:

### 2025-10-30 — API Change

**Added PIX expiration field to MetadataIn**

A new field `PaymentExpirationInMinutes` has been added for PIX transactions in Brazil.  
Merchants can now define a custom expiration time for QR payments.  
This change applies to both **Create Purchase Guide** and **API Reference**.