references/doc-structures.md
# Documentation structure templates
Templates for each documentation type. Adapt based on content needs.
## Platform documentation
For feature documentation in `sources/platform/`.
```markdown
---
title: Feature name in sentence case
description: 140-160 chars explaining user value
sidebar_position: 1.0
slug: /platform/category/feature
---
## Introduction
[Clear description of the feature. What it does, why it matters.]
## When to use [feature]
[Explain use cases and scenarios where this feature is appropriate.]
## Configure [feature]
1. [Step 1 with action verb]
1. [Step 2]
```javascript
// Complete, runnable example
```
## Best practices
- [Practice 1]
- [Practice 2]
## Related features
- [Related feature 1](relative-link)
- [Related feature 2](relative-link)
```
## Guides
For how-to guides explaining problem-solving approaches.
```markdown
---
title: Action-oriented title
description: 140-160 chars explaining what user will accomplish
sidebar_position: 1.0
slug: /path/to/guide
---
## Introduction
[What problem does this guide solve? What will the user accomplish?]
## Prerequisites
- [Required knowledge or setup]
## Step 1: [Action verb] [what to do]
[Explanation and code examples]
## Step 2: [Action verb] [what to do]
[Explanation and code examples]
## Test your setup
[How to verify it works]
## Summary
[What the user accomplished and suggested next steps]
```
## Reference documentation
For technical specifications, API parameters, and configuration options.
```markdown
---
title: Feature reference
description: 140-160 chars about the reference content
sidebar_position: 1.0
slug: /path/to/reference
---
## Overview
[Brief description of what this reference covers.]
## Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| `param1` | `string` | - | Description of param1 |
| `param2` | `number` | `10` | Description of param2 |
## Examples
### Basic usage
```javascript
// Minimal example
```
### Advanced usage
```javascript
// Full-featured example
```
## Related information
- [Related topic](relative-link)
```
references/process.md
# Documentation writing process
Agent-agnostic workflow for writing or editing Apify documentation.
## Step 1: Determine documentation type
| Type | Goal | Location |
|---|---|---|
| Platform docs | Practical guidance for features | `sources/platform/` |
| Guides | Explain how to solve a problem | `sources/platform/` or `sources/academy/` |
| Reference | Technical specifications | `sources/platform/` |
| Tutorial | Step-by-step learning | Use the tutorial workflow instead |
## Step 2: Research
- Read 2-3 existing pages in the same directory to match patterns
- Check `standards/terminology.md` for product name capitalization
- Identify related pages to link to
## Step 3: Create front matter
```yaml
---
title: Sentence case title
description: 140-160 character value-focused description
sidebar_position: 1.0
slug: /path/to/page
---
```
## Step 4: Write content
Follow the structure template for the doc type in `.agents/skills/doc-write/references/doc-structures.md`:
- **Platform docs**: introduction → when to use → configure/use → best practices → related features
- **Guides**: introduction → prerequisites → step-by-step → code examples → testing → summary
- **Reference**: overview → parameters/options → examples → related information
## Step 5: Quality check
- Run `pnpm lint:md` on the new or edited file
- Run `vale "<file>" --minAlertLevel=error`
- Run `pnpm start` (or `pnpm build`) to verify no broken links or slug conflicts
Key rules: US English, active voice, imperative tone, sentence case headings, bold for UI elements only, all admonitions need titles, code blocks need language tags.
## Edge cases
### Editing existing pages
Read the full existing page before making changes. Preserve the existing structure and voice. Only modify what's needed.
### Description length
Front matter `description` must be 140-160 characters for SEO. Focus on user value, not feature lists.
### Page doesn't match sibling pages
Before writing, read sibling pages in the same directory. Match heading structure, code example style, and admonition usage.
SKILL.md
---
name: doc-write
description: Write or edit Apify documentation pages following the style guide. Use when user says "write docs for", "create a new page", "document this feature", "add documentation about", "edit this doc page", or "write a guide for [topic]". Handles platform docs, guides, and reference pages with proper formatting and structure.
allowed-tools: Read Write Edit Bash Glob Grep
argument-hint: topic
---
# Documentation writing
## Process
1. **Determine doc type** - platform docs, guide, or reference (tutorials → use `/tutorial`)
2. **Research** - read related existing pages, check `standards/terminology.md` for product names
3. **Create front matter** - title (sentence case), description (140-160 chars), sidebar_position, slug
4. **Write content** following the structure for the doc type:
- **Platform docs**: intro → prerequisites → main content → code examples → next steps
- **Guides**: intro with goal → step-by-step instructions → verification → troubleshooting
- **Reference**: brief description → parameters/options → examples → related pages
5. **Quality check** - run `pnpm lint:md` and `vale` before finishing
Key rules: US English, active voice, imperative tone, sentence case headings, bold for UI elements only, all admonitions need titles, code blocks need language tags.
For detailed structure templates, see `.agents/skills/doc-write/references/doc-structures.md`.
For edge cases and process notes, see `.agents/skills/doc-write/references/process.md`.