Skip to content

Commit 4c14638

Browse files
mnmkngclaudeTC-MOmarcel-rbro
authored
docs: Add Claude Code writing style guide (#2198)
## Summary Adds a centralized writing style guide for AI-assisted documentation at `.claude/rules/writing-style.md`. **What's in the guide:** - Core principles (simple, factual, technical) - Content type awareness (tutorials vs reference docs) - Formatting rules (headings, bold, italics, lists, admonitions) - Grammar and terminology standards - Link accessibility guidelines - Common mistakes to avoid ## Context This is an experiment in extracting writing style patterns at scale using Claude Code. **The process:** 1. Started with our existing Apify style guide as a baseline 2. Analyzed TC-MO's recent PR reviews to extract recurring feedback patterns 3. Cross-referenced with CONTRIBUTING.md and AGENTS.md to identify gaps 4. Used Claude Code to synthesize these into actionable rules **Why this matters:** If this approach works, we can continuously improve our style guides by mining reviewer feedback rather than relying on manual documentation efforts. The guide gets better as we review more PRs. ## Test plan - [ ] Compare guide against CONTRIBUTING.md and AGENTS.md for contradictions - [ ] Have TC-MO review for accuracy of extracted patterns - [ ] Test with actual doc PRs to see if Claude Code follows the guidelines 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com> Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com> Co-authored-by: Marcel Rebro <marcel.rebro@apify.com>
1 parent 7cf1087 commit 4c14638

18 files changed

Lines changed: 2304 additions & 46 deletions

‎.claude/README.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# Claude Code configuration for Apify docs
2+
3+
This directory contains Claude Code configuration for the Apify documentation repository.
4+
5+
## Structure
6+
7+
```text
8+
.claude/
9+
├── README.md # This file - Quick start guide
10+
├── instructions.md # Main instructions for Claude Code
11+
├── rules/ # Canonical standards (auto-loaded)
12+
│ ├── writing-style.md # Language, tone, grammar
13+
│ ├── content-standards.md # Formatting, front matter, code
14+
│ ├── terminology.md # Apify-specific terms
15+
│ ├── file-organization.md # Naming conventions
16+
│ └── quality-standards.md # Quality checklist
17+
└── skills/ # Reusable skills for common tasks
18+
├── doc-write.md # Documentation writing skill
19+
├── api-doc.md # API documentation skill
20+
├── tutorial.md # Tutorial creation skill
21+
└── review-docs.md # Documentation review skill
22+
```
23+
24+
## How to use
25+
26+
### For Claude Code users
27+
28+
1. **Start a new session**: Claude Code will automatically read `instructions.md`
29+
2. **Use skills**: Type `/doc-write`, `/api-doc`, `/tutorial`, or `/review-docs` to use specific skills
30+
3. **Reference standards**: Always refer to `AGENTS.md` in the repo root for core standards
31+
32+
### Available skills
33+
34+
#### /doc-write
35+
Documentation writing - Create or edit pages following style guide
36+
37+
#### /api-doc
38+
API documentation - Work with OpenAPI specifications and endpoints
39+
40+
#### /tutorial
41+
Tutorial creation - Build structured, educational tutorials
42+
43+
#### /review-docs
44+
Documentation review - Check quality and compliance before submission
45+
46+
## Quick start
47+
48+
### Writing new documentation
49+
50+
```text
51+
Use /doc-write skill to create a new documentation page about [topic]
52+
```
53+
54+
### Creating a tutorial
55+
56+
```text
57+
Use /tutorial skill to create a tutorial on [topic]
58+
```
59+
60+
### Adding API endpoint
61+
62+
```text
63+
Use /api-doc skill to document the new [endpoint-name] endpoint
64+
```
65+
66+
### Reviewing documentation
67+
68+
```text
69+
Use /review-docs skill to review sources/platform/[file-name].md
70+
```
71+
72+
## Documentation standards
73+
74+
All documentation standards are in `.claude/rules/` (auto-loaded):
75+
76+
1. **`writing-style.md`** - Language, tone, grammar, headings, word choice
77+
2. **`content-standards.md`** - Front matter, formatting, code examples, links, images
78+
3. **`terminology.md`** - Apify-specific capitalization and product names
79+
4. **`file-organization.md`** - File naming and directory structure
80+
5. **`quality-standards.md`** - Comprehensive pre-submission checklist
81+
82+
Also reference:
83+
84+
- **`AGENTS.md`** - Vendor-agnostic documentation standards (in repo root)
85+
- **`CONTRIBUTING.md`** - Setup, workflows, contribution process
86+
- **`instructions.md`** - Full Claude Code instructions (in this directory)
87+
88+
## Testing
89+
90+
Before submitting:
91+
92+
```bash
93+
npm run lint:md # Check markdown
94+
npm run lint:code # Check code
95+
npm start # Preview changes
96+
npm test # Validate API specs
97+
```
98+
99+
## Best practices
100+
101+
1. **Read `AGENTS.md` first** - Vendor-agnostic documentation standards
102+
2. **Check `.claude/rules/`** - Auto-loaded standards for writing, formatting, terminology
103+
3. **Use the appropriate skill** - Designed for specific documentation tasks
104+
4. **Run linters before committing** - `npm run lint:md` and `npm run lint:code`
105+
5. **Review before submit** - Use `/review-docs` skill for final checks
106+
107+
## Need help?
108+
109+
- Questions about style: Check `AGENTS.md`
110+
- Setup issues: See `CONTRIBUTING.md`
111+
- Skill usage: Read the specific skill file
112+
- Claude Code general: Visit [Claude Code docs](https://github.com/anthropics/claude-code)

‎.claude/claude.json‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
{
2+
"skills": [
3+
{
4+
"name": "doc-write",
5+
"description": "Create or edit documentation following Apify style guide",
6+
"path": "skills/doc-write.md"
7+
},
8+
{
9+
"name": "api-doc",
10+
"description": "Work with OpenAPI specifications and API documentation",
11+
"path": "skills/api-doc.md"
12+
},
13+
{
14+
"name": "tutorial",
15+
"description": "Create structured tutorials with proper learning progression",
16+
"path": "skills/tutorial.md"
17+
},
18+
{
19+
"name": "review-docs",
20+
"description": "Review documentation for style guide compliance and quality",
21+
"path": "skills/review-docs.md"
22+
}
23+
],
24+
"instructions": "instructions.md",
25+
"context": [
26+
"../AGENTS.md",
27+
"../CONTRIBUTING.md"
28+
]
29+
}

‎.claude/instructions.md‎

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
# Claude Code instructions for Apify documentation
2+
3+
## Project overview
4+
5+
You are working on the Apify documentation repository, which contains:
6+
7+
- **Platform documentation**: Core platform features and functionality (`/sources/platform/`)
8+
- **Academy**: Educational content and tutorials (`/sources/academy/`)
9+
- **API reference**: OpenAPI specifications (`/apify-api/`)
10+
11+
The project uses Docusaurus with MDX, follows Microsoft style guide principles, and has comprehensive style guidelines.
12+
13+
## Primary reference documents
14+
15+
**Always reference these files when working on documentation**:
16+
17+
1. **AGENTS.md** - Primary vendor-agnostic documentation standards (READ THIS FIRST)
18+
2. **.claude/rules/** - Claude Code-specific standards (AUTO-LOADED)
19+
- `writing-style.md` - Language, tone, grammar, and writing guidelines
20+
- `content-standards.md` - Formatting, front matter, code examples, links, images
21+
- `terminology.md` - Apify-specific capitalization and terminology
22+
- `file-organization.md` - File naming and directory structure
23+
- `quality-standards.md` - Comprehensive quality checklist
24+
3. **CONTRIBUTING.md** - Contribution guidelines, setup, and workflows
25+
4. `.cursor/rules/*.mdc` - Cursor-specific rules (for reference)
26+
27+
## Available skills
28+
29+
Use these skills for specific documentation tasks:
30+
31+
### `/doc-write` - Documentation writing
32+
33+
**When to use**: Creating or editing documentation pages
34+
**Handles**: Content creation, formatting, style guide compliance
35+
36+
### `/api-doc` - API documentation
37+
38+
**When to use**: Working with OpenAPI specifications
39+
**Handles**: Creating endpoints, schemas, code samples
40+
41+
### `/tutorial` - Tutorial creation
42+
43+
**When to use**: Creating step-by-step tutorials
44+
**Handles**: Tutorial structure, learning content, examples
45+
46+
### `/review-docs` - Documentation review
47+
48+
**When to use**: Reviewing documentation before submission
49+
**Handles**: Style guide compliance, quality checks, consistency
50+
51+
## Documentation standards
52+
53+
All documentation standards are defined in `.claude/rules/` and are auto-loaded by Claude Code:
54+
55+
- **Writing style**: See `writing-style.md` for language, tone, grammar, headings, and word choice
56+
- **Content formatting**: See `content-standards.md` for front matter, text formatting, admonitions, code examples, links, and images
57+
- **Terminology**: See `terminology.md` for Apify-specific capitalization and product names
58+
- **File organization**: See `file-organization.md` for naming conventions and directory structure
59+
- **Quality assurance**: See `quality-standards.md` for comprehensive pre-submission checklist
60+
61+
**Quick reference**:
62+
63+
- Use sentence case for headings (not Title Case)
64+
- Bold only for UI elements (not emphasis)
65+
- All admonitions must have titles
66+
- Front matter required (title, description 140-160 chars, sidebar_position, slug)
67+
- Use descriptive link text (never "click here")
68+
- All code blocks must specify language
69+
70+
## File organization
71+
72+
### Naming conventions
73+
74+
- Use **kebab-case** for file names: `web-scraping-basics.md` (never camelCase or snake_case)
75+
- Use descriptive names that reflect content
76+
- Group related files in logical directories
77+
- **Match slug to file path** for consistency
78+
79+
### Directory structure
80+
81+
```text
82+
sources/
83+
├── platform/ # Platform documentation
84+
│ ├── actors/ # Actor-related content
85+
│ ├── storage/ # Storage documentation
86+
│ └── integrations/ # Integration guides
87+
└── academy/ # Educational content
88+
├── tutorials/ # Step-by-step guides
89+
└── webscraping/ # Web scraping courses
90+
```
91+
92+
## API documentation specifics
93+
94+
See the `/api-doc` skill for comprehensive OpenAPI specification standards, operation ID conventions, and path file naming.
95+
96+
## Development workflow
97+
98+
### Before starting work
99+
100+
1. Read `AGENTS.md` for documentation standards
101+
2. Review `CONTRIBUTING.md` for specific guidelines
102+
3. Check existing similar documentation for patterns
103+
4. Determine which skill to use for the task
104+
105+
### During development
106+
107+
1. Follow the appropriate skill instructions
108+
2. Reference `AGENTS.md` for style questions
109+
3. Use proper front matter in all files
110+
4. Include complete, tested code examples
111+
5. Add descriptive links and alt text
112+
113+
### Before submitting
114+
115+
1. Run linting checks:
116+
117+
```bash
118+
npm run lint:md # Markdownlint - Markdown syntax/formatting
119+
npm run lint:code # ESLint - Code linting
120+
121+
# Run locally for more detailed output:
122+
npx markdownlint "path/to/file.md" # Markdownlint - Check specific files
123+
vale sync # Vale - Download styles (first time)
124+
vale "path/to/file.md" --minAlertLevel=error # Vale - Check prose style
125+
```
126+
127+
2. Use `/review-docs` skill to check compliance
128+
3. Verify all code examples work
129+
4. Check all links are valid
130+
5. Ensure front matter is complete
131+
132+
### Testing changes
133+
134+
```bash
135+
npm install # Install dependencies
136+
npm start # Start development server
137+
npm test # Validate OpenAPI specs (if applicable)
138+
npm run build # Test production build
139+
```
140+
141+
## Common patterns
142+
143+
See respective skills for content-type specific patterns:
144+
145+
- **Tutorials**: See `/tutorial` skill for 8-section tutorial structure
146+
- **Platform documentation**: See `/doc-write` skill for feature documentation patterns
147+
- **API documentation**: See `/api-doc` skill for endpoint documentation patterns
148+
149+
## Quality checklist
150+
151+
Before considering any documentation complete, see `quality-standards.md` for the comprehensive checklist and use the `/review-docs` skill for final review.
152+
153+
## Best practices
154+
155+
- Start with user's goal/problem
156+
- Provide context before technical details
157+
- Use consistent Apify terminology (see `terminology.md`)
158+
- Structure content logically (basic → advanced)
159+
- Link to related content
160+
- Test all code examples before committing
161+
- Never make assumptions about product features - ask if unsure
162+
- For code review: check comments and obvious mistakes only
163+
164+
## Content review process
165+
166+
### Before reviewing a PR
167+
168+
- Check that the latest changes were pulled from the feature branch
169+
170+
### Review checklist
171+
172+
When reviewing or creating documentation, verify:
173+
174+
- **Clarity**: Instructions are easy to understand
175+
- **Consistency**: Uniform terminology (see word list above) and style throughout
176+
- **Grammar & Spelling**: Correct errors, use American English with Oxford commas
177+
- **Structure**: Logical flow, no duplicate content, appropriate headings/lists
178+
- **Links**: Verify all links are functional and relevant, link key terms to their docs
179+
- **Code snippets**: Developer-provided; check comments and obvious mistakes only (not full code review)
180+
181+
## Getting help
182+
183+
If you're unsure about:
184+
185+
- **Style questions**: Check `AGENTS.md` first
186+
- **Setup issues**: See `CONTRIBUTING.md`
187+
- **API documentation**: See `/api-doc` skill
188+
- **Tutorial structure**: See `/tutorial` skill
189+
- **Review process**: See `/review-docs` skill
190+
- **Product features**: Never make assumptions - ask if unsure
191+
192+
## Project-specific context
193+
194+
### Multiple repositories
195+
196+
The full documentation ecosystem includes multiple repos:
197+
198+
- apify-docs (this repo) - Platform, Academy, OpenAPI
199+
- apify-client-js - JavaScript client docs
200+
- apify-client-python - Python client docs
201+
- apify-sdk-js - JavaScript SDK docs
202+
- apify-sdk-python - Python SDK docs
203+
- apify-cli - CLI documentation
204+
205+
### Theme
206+
207+
Uses `@apify/docs-theme` package - don't modify theme files directly.
208+
209+
### Deployment
210+
211+
- Automatic deployment on merge to `master`
212+
- Preview builds available for pull requests
213+
- Uses nginx for routing between repositories
214+
215+
### Linting tools
216+
217+
- **markdownlint** - Markdown syntax and formatting validation
218+
- **eslint** - JavaScript/TypeScript code linting
219+
- **Vale** - Prose style checking (optional, download styles with `vale sync`)
220+
221+
## Remember
222+
223+
The goal is to help users succeed with Apify. Every piece of documentation should:
224+
225+
- Be **clear** and easy to understand
226+
- Be **accurate** and technically correct
227+
- Be **actionable** with concrete examples
228+
- Follow the **style guide** consistently
229+
- Provide **real value** to users
230+
231+
When in doubt, prioritize clarity and usefulness over strict adherence to rules. But always maintain consistency within the documentation set.

0 commit comments

Comments
 (0)