diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000000..e46d3269d3 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,5 @@ + diff --git a/AGENTS.md b/AGENTS.md index bd4030aab5..a0e04c9243 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -132,7 +132,7 @@ Use `pnpm start:dev` + nginx to serve all repos together locally. See `CONTRIBUT - Auto-deploy on merge to `master` - Preview builds on pull requests - PR titles must use [Conventional Commits](https://www.conventionalcommits.org/) format (`docs:`, `fix:`, `feat:`, etc.) - enforced by CI -- Keep PR descriptions short - one or two sentences covering what changed and why. Skip boilerplate headings (`## Summary`, `## Changes`, `## Details`), bullet lists that restate the diff, and filler text. The diff is the record of what changed; the description explains the why. +- Keep PR descriptions to one or two sentences - what changed and why. No boilerplate headings, no bullet lists restating the diff. See the pull request process in `CONTRIBUTING.md` ## Common pitfalls @@ -152,7 +152,7 @@ Use `pnpm start:dev` + nginx to serve all repos together locally. See `CONTRIBUT ## Standards -Detailed writing and formatting standards are in `standards/`: +Detailed writing and formatting standards are in `standards/`. This is the single source of truth for docs rules - `CONTRIBUTING.md` and `.cursor/rules/` point here instead of restating them, so a rule change lands in `standards/` only: - `standards/writing-style.md` - Prose voice, tone, headings, links, numbers - `standards/content-standards.md` - Front matter, admonitions, code blocks, images @@ -167,7 +167,8 @@ Key rules at a glance: - Sentence case headings, no gerunds - Bold for UI elements only; `code` for filenames, commands, variables - All admonitions require titles -- 140-160 character descriptions in front matter +- 140-160 character descriptions in front matter, action-oriented, without the word "documentation" +- Screenshots only when they add something the prose doesn't; light theme, `#F86606` highlights, no arrows - See `standards/terminology.md` for Apify product name capitalization - Don't use em dashes (—) - use hyphen with spaces ( - ) instead @@ -190,7 +191,7 @@ When creating or reviewing documentation, verify: - [ ] All admonitions have titles - [ ] Code examples are complete with syntax highlighting - [ ] Links use descriptive text, internal links use relative paths -- [ ] Images have alt text, use light theme +- [ ] Images have alt text, use light theme and `#F86606` highlights - [ ] Terminology matches rules above - [ ] US English, active voice, no sales language - [ ] `pnpm lint` passes diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8c08a2a093..6a386c71a8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,7 @@ 1. Review this guide completely 2. Setup you development environment -3. Familiarize yourself with our documentation style guide +3. Familiarize yourself with the [documentation style guide](standards/) ## Development setup @@ -77,65 +77,16 @@ You should be able to open https://docs.apify.loc in your browser and run all th ## Documentation style guide -### Language guidelines +The style guide lives in [`standards/`](standards/), which is the single source of truth for both people and AI assistants. Rules aren't repeated here, so there's nothing to keep in sync: -- Use US English -- Write in inclusive language -- Avoid directional language (like "left" or "right" or instead of "see" use "check out") -- Use active voice whenever possible +- [`standards/writing-style.md`](standards/writing-style.md) - US English, active and inclusive voice, headings, text emphasis, links, numbers +- [`standards/content-standards.md`](standards/content-standards.md) - Front matter, admonitions, code blocks and code tabs, images and screenshots +- [`standards/terminology.md`](standards/terminology.md) - Apify product names, capitalization, article usage +- [`standards/grammar-rules.md`](standards/grammar-rules.md) - Hyphenation, punctuation, numbers, brand spelling +- [`standards/file-organization.md`](standards/file-organization.md) - File naming (kebab-case) and directory structure +- [`standards/quality-standards.md`](standards/quality-standards.md) - Checklist to run through before opening a pull request -### Formatting conventions - -1. Text emphasis: - - - use **Bold** for UI elements - - use _Italics_ for emphasis - - use `code` for inline code, by using back-ticks (\`\`\) - - use code blocks with language specification - - use [code tabs](https://docusaurus.io/docs/markdown-features/tabs) whenever you want to include examples of implementation in more than one language - -2. Documentation elements: - - - Use [admonitions](https://docusaurus.io/docs/2.x/markdown-features/admonitions) to emphasize crucial information, available admonitions are: - - note - - tip - - info - - caution - - danger - - Use code tabs for multiple languages - - Include proper metadata in front matter - - Use concise, meaningful headings: - - Use sentence case. - - Avoid question-like titles ("How to...", "What is..."). - - Don't use gerunds. - - Example of proper usage and formatting: - - ```text - :::note Your Title Here - - Your important message here. - - ::: - ``` - -3. Screenshots: - - - Keep screenshots to a minimum. If an image shows what your prose already describes, it's probably not needed. - - Always include meaningful alt texts. Remember that it might be the only way for some users to understand the content. - - Use light theme when taking screenshots. - - To highlight UI elements, use `#F86606` color for indicators. Don't use arrows. - -### Front matter metadata best practices - -- Keep descriptions between 140 and 160 characters -- Use action-oriented phrasing -- Avoid repetitive keywords -- Avoid the word "documentation" in descriptions - -### File naming conventions - -For file names, use lowercase letters and hyphens (kebab-case). For example `web-scraping-basics.mdx` +[`AGENTS.md`](AGENTS.md) condenses these into the rules an AI assistant loads first. Change a rule in `standards/`, not in `AGENTS.md` or here. ## AI assistant rules structure @@ -344,9 +295,9 @@ Add languages by adding new folders at the appropriate path level. ## Pull request process -1. Follow [Conventional Commits](https://www.conventionalcommits.org/) -2. Pass all CI checks -3. Include comprehensive documentation updates +1. Title follows [Conventional Commits](https://www.conventionalcommits.org/) - CI enforces it +2. Description is one or two sentences: what changed and why. Skip boilerplate headings (`## Summary`, `## Changes`) and bullet lists that restate the diff - the diff is the record of what changed, the description explains the why. [`.github/pull_request_template.md`](.github/pull_request_template.md) repeats this as a reminder in the PR form +3. All CI checks pass ## Deployment diff --git a/README.md b/README.md index 184b2a4bd3..7dd880faab 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ Documentation ecosystem consists of: **Before contributing, read these essential resources:** - [Contributing guidelines](CONTRIBUTING.md) - Complete setup and contribution process -- [Documentation style guide](CONTRIBUTING.md#documentation-style-guide) - Writing standards and formatting +- [Documentation style guide](standards/) - Writing standards and formatting, the source of truth for people and AI assistants - [AI Assistant Rules Structure](CONTRIBUTING.md#ai-assistant-rules-structure) - AI tool configuration ### Prerequisites diff --git a/standards/content-standards.md b/standards/content-standards.md index b2420867ad..22bd612b09 100644 --- a/standards/content-standards.md +++ b/standards/content-standards.md @@ -18,7 +18,7 @@ slug: /path/to/page ### Required fields - **title**: Sentence case, present tense (e.g., "Create your first Actor") -- **description**: 140-160 characters for SEO, clear and actionable +- **description**: 140-160 characters for SEO, clear and actionable. Use action-oriented phrasing, avoid repeating the same keyword, and don't use the word "documentation" - **sidebar_position**: Decimal number for ordering (1.0, 1.1, 2.0, etc.) - **slug**: URL path starting with `/` (e.g., `/platform/actors/running`) @@ -189,6 +189,10 @@ All images must include meaningful alt text describing the content: ![Apify Console showing the Actor creation dialog](./images/create-actor.webp) ``` +### When to use a screenshot + +Keep screenshots to a minimum. If an image only shows what the prose already describes, leave it out. Screenshots go stale with every UI change, so add one when it carries information the text can't. + ### Theme Screenshots should use: @@ -198,10 +202,11 @@ Screenshots should use: ### Visual indicators -Use red boxes or arrows to highlight important UI elements: -- **Red border**: Highlight clickable elements (buttons, fields) -- **Red arrow**: Point to specific areas -- **Red circle**: Highlight small elements +Highlight UI elements with the `#F86606` (Apify orange) color: +- **Border**: Highlight clickable elements (buttons, fields) +- **Circle**: Highlight small elements + +Don't use arrows. ### Image format diff --git a/standards/quality-standards.md b/standards/quality-standards.md index b784558c34..d2ed4dc7fb 100644 --- a/standards/quality-standards.md +++ b/standards/quality-standards.md @@ -80,7 +80,8 @@ Before submitting documentation, verify: - [ ] All images include meaningful alt text - [ ] Screenshots use light theme -- [ ] Red indicators used to highlight UI elements +- [ ] UI highlights use `#F86606`, no arrows +- [ ] Screenshots earn their place (no image that only repeats the prose) - [ ] Images stored in `images/` subdirectory - [ ] Image format is appropriate (WebP for screenshots, SVG for logos, icons, and product images) diff --git a/standards/writing-style.md b/standards/writing-style.md index d20c73d8cf..bea8865e50 100644 --- a/standards/writing-style.md +++ b/standards/writing-style.md @@ -75,6 +75,7 @@ Use active voice. Avoid gendered terms. Don't use directional language ("left/ri | The Actor is started by the user | The user starts the Actor | | He can configure his settings | You can configure your settings | | Click the button on the left | Click the **Settings** button | +| See the storage guide | Check out the storage guide | ### Avoid "our" @@ -112,7 +113,6 @@ Acceptable uses of "our" - direct team actions or invitations: | API Reference Documentation | API reference documentation | Keep acronyms capitalized, rest lowercase | | Working With Docker Containers | Work with Docker containers | "Docker" stays capitalized (product name) | | Extend The Base Image | Extend the base image | Lowercase "the" mid-sentence | -| How Do I Start? | How do I start? | Capitalize "I" in questions | | Understanding Request Queues | Understand request queues | Lowercase feature names | | Enable Standby Mode | Enable standby mode | Lowercase mode names | | Access The Apify Console | Access Apify Console | "Apify Console" stays capitalized (product), no "the" | @@ -127,6 +127,13 @@ Acceptable uses of "our" - direct team actions or invitations: > Enforced by Vale (`Apify.HeadingGerund`). Run `vale ""` to check. +**No question-like headings.** Answer the question instead of asking it. + +| Avoid | Prefer | +| ---------------------------- | ----------------------- | +| How to run an Actor | Run an Actor | +| What is a request queue? | Request queues | + ## Text formatting ### Bold