acme-platform-docs

Enterprise documentation for the ACME Cloud Platform. Built with Docs-as-Code — Markdown source, Git-versioned, CI/CD deployed.

📄 Total Pages

147

↑ 12 this month

🔀 Git Commits

1,284

↑ 38 this week

⚡ Build Time

4.2s

↑ 18% faster

◉ Style Score

↑ 3 pts

CI/CD Pipeline

📝

Markdown Source

docs/*.md

→

🔀

Git + PR

Review & Merge

→

◉

Lint & Validate

Style + Links

→

⚙

Build

SSG Transform

→

📦

Multi-Format

HTML · PDF · JSON

→

🚀

Deploy

CDN + Versioned

Recent Builds

a3f7c2d feat: add webhook configuration guide Passed 4.2s 3 min ago

e91b4a8 fix: broken links in authentication section Passed 3.8s 1 hr ago

7d2f0c1 docs: update API rate limits for v2.4 Passed 4.5s 3 hrs ago

b5c8e3a refactor: reorganize getting-started topics Failed 1.2s 5 hrs ago

f4a6d91 feat: add SDK quickstart for Python and Node Passed 4.1s 8 hrs ago

📁 Project Structure

📁 acme-platform-docs/
📄 docforge.config.yml
📄 package.json
📄 .github/workflows/deploy.yml
📁 docs/
📄 index.md
📁 getting-started/
📄 quickstart.md
📄 installation.md
📄 authentication.md
📁 guides/
📄 webhooks.md
📄 pagination.md
📁 api-reference/
📄 payments.md
📄 customers.md
📄 openapi.yaml
📁 troubleshooting/
📁 static/
📁 templates/

📊 Content Metrics

Concepts (DITA) 34

Tasks (How-to) 42

API Reference 38

Tutorials 18

Troubleshooting 15

Release Notes 24

Total Words 128,450

quickstart.md

authentication.md

docforge.config.yml

openapi.yaml

Source Markdown + YAML FM

---
title: "Quickstart Guide"
description: "Get up and running with the ACME Platform API in under 5 minutes."
topic_type: tutorial
audience: developer
last_updated: 2025-02-26
version: 2.4
sidebar_position: 1
tags: [getting-started, api, quickstart]
---

# Quickstart Guide

Get up and running with the ACME Platform API in under 5 minutes. This guide walks you through authentication, your first API call, and handling responses.

## Prerequisites

Before you begin, make sure you have:

- An ACME Platform account ([sign up here](https://acme.dev/signup))
- Your API key from the **Dashboard → Developer → API Keys** page
- A REST client like `curl`, Postman, or an HTTP library in your language

> **Note:** Use your `sk_test_` key for development. Test mode requests never affect production data or incur charges.

## Step 1: Install the SDK

Choose your preferred language:

```bash
# Python
pip install acme-platform

# Node.js
npm install @acme/platform-sdk

# Go
go get github.com/acme/platform-go
```

## Step 2: Authenticate

Every request must include your API key in the `Authorization` header:

```python
import acme

client = acme.Client(api_key="sk_test_your_key_here")

# Verify your connection
account = client.account.retrieve()
print(f"Connected as: {account.name}")
```

## Step 3: Create Your First Resource

Let's create a customer record:

```python
customer = client.customers.create(
    email="ada.lovelace@example.com",
    name="Ada Lovelace",
    metadata={
        "plan": "enterprise",
        "source": "quickstart"
    }
)

print(f"Created customer: {customer.id}")
# Output: Created customer: cus_Rk4x7LmN2vPq
```

## Step 4: Handle Errors

The SDK raises typed exceptions you can catch:

```python
from acme.errors import ValidationError, AuthenticationError

try:
    customer = client.customers.create(email="invalid")
except ValidationError as e:
    print(f"Validation failed: {e.message}")
    print(f"Field: {e.param}")
except AuthenticationError:
    print("Check your API key")
```

## What's Next?

| Guide | Description |
|-------|-------------|
| [Authentication](/guides/auth) | Deep dive into API keys, OAuth, and scopes |
| [Webhooks](/guides/webhooks) | Receive real-time event notifications |
| [Pagination](/guides/pagination) | Navigate large result sets efficiently |
| [Error Handling](/guides/errors) | Complete error reference and best practices |

> **Tip:** Enable webhook events early in development — they're essential for production-ready integrations.

Preview Rendered HTML

Content Architecture

Topic-based information architecture following DITA principles. Content is structured as reusable, single-purpose topics.

📊 Topic Taxonomy

Concept Topics

Explain what something is — definitions, overviews, architecture

Task Topics

Step-by-step procedures — how to accomplish a specific goal

Reference Topics

Lookup information — API specs, parameters, config options

Tutorials

End-to-end guided learning paths with progressive complexity

Troubleshooting

Problem → Cause → Solution patterns for common issues

Sample Topics

Concept

Platform Architecture Overview

High-level overview of the ACME microservices architecture, data flow, and component relationships.

1,240 words·Updated 2d ago

Task

Configure Webhook Endpoints

Set up HTTP endpoints to receive real-time notifications when events occur in your ACME account.

890 words·Updated 5d ago

Reference

Payments API: Endpoints

Complete reference for all Payment endpoints including parameters, response schemas, and status codes.

2,100 words·Updated 1d ago

Tutorial

Build a Checkout Flow

End-to-end tutorial for building a complete payment checkout using the SDK, webhooks, and error handling.

3,400 words·Updated 1w ago

Troubleshoot

Payment Declines

Common causes of payment failures and step-by-step resolution for each decline code.

1,050 words·Updated 3d ago

API Spec

OpenAPI 3.1 Specification

Machine-readable API definition auto-generating endpoint docs, SDKs, and Postman collections.

openapi.yaml·Auto-synced

Style Guide Linter

Automated checks against Microsoft Writing Style Guide, Vale, and custom project rules.

Overall Score

Readability

Consistency

100

Links Valid

Lint Results: 7 findings across 4 files

Last run: 3 min ago

Error

Microsoft.Passive

"The payment was declined by the issuing bank" — Use active voice for clarity.

✦ Fix: "The issuing bank declined the payment"

payments.md:42

Error

DocForge.TaskFirst

Task topic starts with background context instead of user goal. Lead with the action.

✦ Fix: Start with "To configure webhooks, ..." instead of "Webhooks are a way to..."

webhooks.md:1

Warn

Vale.Readability

Flesch-Kincaid grade level is 14.2 — aim for ≤ 10 for developer docs.

✦ Simplify long sentences in the "Architecture Overview" section

architecture.md

Warn

Microsoft.Wordiness

"In order to" → "To" — Remove unnecessary wordiness.

✦ 3 occurrences found

quickstart.md:18,31,56

Info

DocForge.Terminology

Inconsistent capitalization: "API key" vs "API Key" vs "api key".

✦ Standardize to "API key" (lowercase 'key') per style guide

Multiple files

Info

DocForge.ProgressiveDisclosure

Reference page exceeds 2,500 words. Consider splitting into sub-topics for scannability.

✦ Split into: "Endpoints", "Request Parameters", and "Response Schema"

payments.md

Info

DocForge.CodeSamples

4 endpoints missing code samples in non-primary languages (Go, Ruby).

✦ Add SDK examples for all supported languages

api-reference/*.md

Build Outputs

Single Markdown source → multiple publication formats. Content is treated as source code; all outputs are regenerable artifacts.

🌐

Static HTML

Responsive docs site via SSG

📕

PDF Manual

Print-ready with ToC & index

⚡

OpenAPI Spec

Auto-generated from source

{ }

JSON / Headless

Structured content for CMS/apps

📮

Postman Collection

Ready-to-import API testing

📋

Changelog

Auto from Git commit history

Static HTML: Build Preview

↓ Download

Configuration

Project settings defined in docforge.config.yml — the single source of truth for your docs pipeline.

# docforge.config.yml — Project Configuration # This file controls the entire docs-as-code pipeline project: name: "ACME Platform Documentation" version: "2.4.0" base_url: "https://docs.acme.dev" repo: "https://github.com/acme/platform-docs" source: content_dir: "./docs" static_dir: "./static" templates_dir: "./templates" openapi_spec: "./docs/api-reference/openapi.yaml" build: engine: "docforge-ssg" # Static site generator output_dir: "./dist" clean_build: true formats: - html # Responsive docs site - pdf # Print-ready manual - json # Headless CMS / API - openapi # Generated spec lint: enabled: true style_guide: "Microsoft" # Base style guide vale_config: ".vale.ini" custom_rules: - "rules/task-first.yml" # Enforce task-oriented structure - "rules/terminology.yml" # Product term consistency - "rules/progressive.yml" # Content length & disclosure fail_on: "error" # Block deploys on errors link_check: true versioning: strategy: "git-tag" # Semantic versioning from tags show_versions: true latest_redirect: true deploy: provider: "cloudflare-pages" branch: "main" preview_branches: true # Deploy PR previews custom_domain: "docs.acme.dev" search: provider: "algolia" index_on_build: true analytics: provider: "plausible" track_search: true track_feedback: true

⚙ Build Settings

Auto-build on push

Trigger a build whenever commits are pushed to main

PR preview deployments

Deploy a preview site for every pull request

Lint gate on PRs

Block merges if lint errors are found

Link validation

Check all internal and external links during build

Search indexing

Re-index content on Algolia after each deploy

🎨 Style Guide Rules

Base style guide

Foundation rules for prose quality

Task-first enforcement

Require task topics to lead with user goals

Max topic length

Warn when a single topic exceeds word limit

Reading level target

Flesch-Kincaid grade level ceiling

Documentation that ships
like software

From plain text to published documentation

Documentation that behaves like code

Everything in the Documentation Center Dashboard

Real documentation, production quality

Explore the Documentation Center Dashboard

acme-platform-docs

📁 Project Structure

📊 Content Metrics

Content Architecture

📊 Topic Taxonomy

Style Guide Linter

Lint Results: 7 findings across 4 files

Build Outputs

Static HTML: Build Preview

Configuration

⚙ Build Settings

🎨 Style Guide Rules

Documentation that shipslike software

From plain text to published documentation

Documentation that behaves like code

Everything in the Documentation Center Dashboard

Real documentation, production quality

Explore the Documentation Center Dashboard

acme-platform-docs

📁 Project Structure

📊 Content Metrics

Content Architecture

📊 Topic Taxonomy

Style Guide Linter

Lint Results: 7 findings across 4 files

Build Outputs

Static HTML: Build Preview

Configuration

⚙ Build Settings

🎨 Style Guide Rules

Documentation that ships
like software