Markdown Editor
Mở trình soạn thảo

Bộ mẫu người viết tài liệu API

Tổng quan API, tổng quan SDK, quickstart, tutorial, how-to, tham chiếu, giải thích, hướng dẫn nhà phát triển, changelog API, thông báo ngừng hỗ trợ, hướng dẫn di chuyển và xử lý sự cố.

Bước 1

Hướng dẫn

  1. API Overview and Getting Started Template

    Chuẩn

    API landing page: what it does, OpenAPI and Arazzo descriptions, base URLs, auth in 3 steps, first request, key resources, errors, limits, next steps

    OpenAPI 3.2.1 (or 3.1.x); Arazzo 1.1.0; Overlay 1.2.0

  2. SDK Overview Template

    Đầy đủ

    SDK landing page: supported-languages matrix, install, auth and config, first call, errors, retries and timeouts, pagination, logging, versioning and support policy

    OpenAPI 3.2.1; Semantic Versioning 2.0.0

  3. Quickstart Guide Template

    Chuẩn

    Quickstart page: time-to-first-success target, prerequisites table, three steps with expected output, verify, clean-up, troubleshooting

    Diátaxis (tutorial and how-to types, adapted)

  4. Tutorial Template (Diátaxis)

    Chuẩn

    Diátaxis tutorial – learning goals, prerequisites, numbered lessons with visible results, checkpoints, troubleshooting

    Diátaxis

  5. How-To Guide Template (Diátaxis)

    Chuẩn

    Goal-oriented how-to guide: prerequisites table, numbered steps with checks, verification, variations, failure table, worked example

    Diátaxis (how-to guide)
Bước 2

Thiết kế tham chiếu

  1. REST Endpoint Reference Template

    Chuẩn

    One REST endpoint: auth, parameter tables, request example, responses per status, RFC 9457 errors, limits, idempotency, paging, deprecation headers

    OpenAPI 3.2.1 (or 3.1.x), Arazzo 1.1.0, Overlay 1.2.0, RFC 9457, RFC 9745, RFC 8594

  2. Reference Documentation Template (Diátaxis)

    Chuẩn

    Diátaxis reference page – neutral, consistently structured entries for functions, types, errors and constants

    Diátaxis

  3. Explanation Document Template (Diátaxis)

    Chuẩn

    Understanding-oriented explanation: idea in brief, context, mechanism diagram, alternatives considered, trade-offs, misconceptions, worked example

    Diátaxis (explanation)

  4. Developer and SDK Guide Template

    Đầy đủ

    Developer guide: setup, auth, multi-language quick start, errors, pagination, rate limits, webhooks, sandbox, OpenAPI/Arazzo/Overlay descriptions, versioning

    OpenAPI 3.2.1 (or 3.1.x); Arazzo 1.1.0; Overlay 1.2.0; RFC 9745, RFC 8594
Bước 3

Quản lý thay đổi

  1. API Changelog Template (OpenAPI 3.2, AsyncAPI 3.1)

    Đầy đủ

    Dated per-version API change log: additive, behavioural and breaking classes, affected operations, OpenAPI diff links, Deprecation and Sunset values, SDK versions

    OpenAPI 3.2.1; AsyncAPI 3.1.0; RFC 9745; RFC 8594

  2. Deprecation Notice Template (RFC 9745, RFC 8594)

    Đầy đủ

    Customer-facing deprecation and sunset notice: affected users, dates, replacement, migration steps, usage detection, Deprecation and Sunset headers, email and changelog variants

    RFC 9745; RFC 8594; OpenAPI 3.2.1

  3. Migration Guide Template

    Chuẩn

    Upgrade/migration guide – who is affected, breaking changes table, timeline, checklist, steps, before/after code, rollback

Bước 4

Bảo trì

  1. Troubleshooting Guide Template

    Chuẩn

    Troubleshooting guide: diagnostic first steps, symptom index, decision steps per problem with verification, data to collect before contacting support, known issues link

    Structure aligned with ISO/IEC/IEEE 26514:2022

  2. llms.txt Template for LLM-Friendly Docs

    Gọn

    llms.txt site index for language models: H1, summary, link-list sections, Optional section, llms-full.txt, .md page mirrors, rel alternate/describedby discovery

    llms.txt proposal v2 (llmstxt.org, modified 2026-08-10)