kocal/symfony-contribution-skills/symfony-docs-contribution

When to Activate

Use when writing or editing reStructuredText (.rst) documentation for symfony/symfony-docs or for a Symfony package's own docs (bundles, UX, AI, ...). Covers RST syntax, the documentation writing standards, and the doc PR workflow.

For PHP code changes, use the symfony-code-contribution skill instead.

Core Rules

1. US English, second person, gender-neutral. Write American English (Merriam-Webster), address the reader as "you" (never "we"), use they/them rather than he/she.
2. RST, not Markdown. Double backticks for inline code, list markers flush to the line start, .. code-block:: <lang> for code. Single backticks and indented lists are Markdown habits — don't.
3. Wrap prose at ~80 chars, code examples at ~85. Define hyperlinks at the bottom of the page — no inline link targets.
4. Title Case headings with the correct underline character per level (see below).
5. Realistic code examples that follow the Symfony coding standards and best practices — no foo/bar; use Acme as the vendor and example.com/.org/.net as domains.
6. Target the right branch and keep one topic per PR. Docs are licensed CC BY-SA 3.0.

reStructuredText Format

Headers — underline (and for level 1, overline) with the text's exact width:

Lists start at column 0 (no indentation). - or * for unordered, numbers for ordered.

Code blocks — .. code-block:: <lang> then an indented block; default language is PHP. Common languages: php, yaml, xml, twig, html+twig, html+php, bash, terminal, json, diff, text, env, php-symfony, php-standalone, php-attributes.

.. code-block:: yaml
 
    framework:
        secret: '%env(APP_SECRET)%'

Multi-format config — show a config in several formats with .. configuration-block:: wrapping nested .. code-block:: directives. Use .. tabs:: / .. tab:: Name for tabbed content (e.g. install methods).

Directives: .. note::, .. warning::, .. versionadded:: X.Y, .. deprecated:: X.Y, and .. _target-name: to define a cross-reference anchor. Directive content must be indented.

Inline roles:

• Inline code: ` double backticks ` (never single).
• Emphasis: *italic*, **bold** — don't span markup across lines.
• Internal page: ` :doc:/path/to/page or :doc:Custom text </path/to/page> (absolute path, no .rst`).
• Anchor: ` :ref:Text <target-name> `.
• Symfony API: ` :class:Symfony\\Component\\...\\ClassName , :method:Symfony\\...\\ClassName::method `.
• Native PHP: ` :phpclass:SimpleXMLElement , :phpmethod:DateTime::createFromFormat , :phpfunction:iterator_to_array `.

Writing Standards

• Avoid these words: basically, clearly, easy/easily, just, logically, merely, obviously, of course, quick/quickly, simply, trivial.
• Contractions are fine (you'd, it's). Do not use serial (Oxford) commas.
• Titles use Title Case: capitalize the first word and every word except closed-class words (articles, prepositions, conjunctions) — "The Vitamins are in my Fresh California Raisins".
• Keep bold/italic within a single line.
• Use :: PHP shorthand inline, unless it would be alone on its line — then use a .. code-block:: php.

Config format order (show the supported formats in this order):

• YAML: add a space after { and before } ({ _controller: ... }) — but not in Twig templates.

Code examples:

• Start with a filename comment (// config/services.php); no blank line after it unless the next line is also a comment.
• Fold whole lines with a language comment: // ... (PHP), # ... (YAML/bash), {# ... #} (Twig), <!-- ... --> (XML/HTML), ; ... (INI). Fold part of a line with a bare ....
• Prefix every bash line with $.
• Reference directories with a trailing slash (bin/), file extensions with a leading dot (.xml), and the project root as your-project/.

Images: create/edit diagrams with Dia. Alt text: concise, capital first letter, trailing period, no "A screenshot of" / "Diagram of" preamble unless the type matters.

Workflow

1. Typo / small reword: use the "Edit this page" button on symfony.com to edit the .rst directly on GitHub.
2. Larger change: fork symfony/symfony-docs, add the upstream remote, and branch from the right base — bug/inaccuracy fix -> oldest maintained branch that has it (merges up); new-feature docs -> the branch of the version that introduces it. Name it improve_xxx or fix_xxx.
3. Edit the .rst, following the format and standards above.
4. Push to your fork; open the PR against that base branch with a clear description. Open a draft PR if it's still WIP; validate large restructurings with the docs team via an issue first. Keep unrelated changes in separate PRs.
5. Fix what the automated checks (syntax, broken links, typos) report; address reviewer suggestions on the same branch.

Reference

Canonical sources in symfony/symfony-docs:

• contributing/doc.rst
• contributing/documentation/format.rst
• contributing/documentation/standards.rst

Examples