drupal-writing-documentation

name	drupal-writing-documentation
description	Guidance for writing or updating Drupal-facing documentation—README files, change records, module help, and technical notes—for core, contrib, and custom work. Emphasizes audience, accuracy, and linking to canonical sources.
metadata	{"status":"draft","drupal-version":"10.3+","last-reviewed":"2026-04"}

How to write excellent documentation for Drupal

When to use this guidance

You are writing or editing documentation for the Drupal project — whether that is a drupal.org wiki page, API documentation in source code, a contrib module README, or a user guide. Drupal's documentation ecosystem is fragmented across several distinct systems with different editing workflows, and there are community conventions around quality and scope that are not obvious to newcomers.

Understanding where Drupal documentation lives

Drupal documentation exists in several distinct silos, each with a different editing workflow.

drupal.org wiki pages are the most common. Anyone with a drupal.org account can edit them. Pages are organised into guides; many guides have one or more named maintainers listed in the right-hand sidebar, but maintainers are often inactive. To understand who has been actively working on a page, use the "Discussion" tab in the top-right navigation widget — it shows the full revision history and contributors. Assume that most edits are minor fixes by drive-by contributors, not the original author.

api.drupal.org is generated directly from Drupal core's source code. If something is wrong or missing on api.drupal.org, the fix goes in the source code (docblocks, inline comments), not on the website. Changes appear on the API site after the next generation run.

The Drupal User Guide is maintained as AsciiDoc files inside a drupal.org project. You cannot edit it by clicking an Edit button on drupal.org. Propose changes by working with the source files in that project.

The Drupal CMS User Guide follows the same pattern but uses Markdown files in a separate git repository. The two guides overlap significantly but cover different products (Drupal core vs. Drupal CMS).

Contrib module documentation on drupal.org is technically open to anyone, but is typically maintained by the module's contributors. Coordinate with them when making substantive changes.

Writing good API documentation

The basics — documenting function parameters and return values — are usually done adequately. What is most often missing:

• When and why to use this function. Don't just describe what it does. Explain the situations where a developer should reach for it, and situations where they should not.
• Relationship to the broader ecosystem. A single method or function is rarely used in isolation. Explain how it fits into the surrounding API subsystem. For example: how does this hook relate to the Entity API? Providing these pathways saves developers from shooting themselves in the foot because they only understood one piece of a larger picture.

Core principles for all Drupal documentation

Document Drupal; link to everything else

Drupal's documentation should document Drupal, and link out to documentation for other tools. A common mistake is embedding lengthy instructions for third-party tools (how to install Docker, how to configure Apache virtual hosts, how to set up PHP) inside Drupal docs. Those instructions go stale quickly and are already better maintained elsewhere. Focus on the Drupal-specific steps, and link to the authoritative source for anything that isn't Drupal.

Be opinionated

Avoid content sprawl driven by trying to cover every possible option. Readers — especially beginners — need a recommended path they can follow with confidence. Give them one. If multiple valid approaches exist, name the community-preferred one first and be explicit: "Start with DDEV. If that doesn't work for your situation, here are alternatives." Then list the alternatives with links rather than full documentation for each.

This is the difference between knowledge (documenting every feature and every option) and wisdom (documenting how people actually use things successfully).

Know your audience

Before writing, picture the person reading this page. Is this someone encountering Drupal or this subsystem for the first time? Or is it reference documentation for experienced developers who just need a quick reminder? The right level of detail is completely different for each. Drupal developers are generally experienced engineers — do not over-explain things that are not Drupal- specific. Do cover the parts that are genuinely Drupal-specific and surprising.

Keep pages short and scannable

Most readers arrive with a specific question. They want to scan the page, find the relevant section, and ignore everything they already know. Prefer:

• Minimum words needed to get the message across.
• Multiple shorter pages over one very long page, as long as the hierarchy is clear.
• Headings and structure that let readers skip to the part they need.

Shorter, well-structured pages also rank better in search engines and are easier for LLMs to retrieve relevant context from.

Use Drupal's terminology correctly

Drupal has a specific vocabulary where common words carry precise meanings (entity, node, bundle, field, region, block). Use these terms correctly so that experienced Drupal developers immediately understand what you mean. Read the Drupal Content Style Guide before writing. Key rules from the style guide include:

• Drupal is always capitalised.
• JavaScript is always one word, capital J, capital S.

Nobody will refuse your contribution for a style guide violation, but following it improves quality and reduces the editing burden on maintainers.

Common mistakes to avoid

Do not document things that aren't Drupal-specific. If a configuration step is the same for any PHP application, it belongs in the tool's own documentation, not on drupal.org.

Do not document every possible option. A page that exhaustively lists every IDE ever invented, with full configuration instructions for each, is less useful than one that says "use PhpStorm or VS Code; here's what you need for either." Completeness is not the same as usefulness.

Do not bury the key steps. If there is a short path to success — a handful of commands that get most people to a working result — put that first, ideally as a TL;DR or quick-start block. Explanation can follow for readers who want to understand what they are doing and why.

Do not assume your page will live in isolation. Link generously to related pages, upstream guides, and API documentation so that readers can get the broader context they need.

A good example to follow

The drupal.org page for setting up a local Drupal development environment is a strong model:

• Clear, specific audience (someone setting up their first local environment).
• TL;DR at the top: copy-paste commands for people who just want to get started.
• Enough explanation below to understand what those commands do and why.
• Opinionated recommendation (DDEV) with acknowledgment that other valid options exist and links to them, without embedding full documentation for each.

Getting help

For general documentation guidance — style questions, the drupal.org IA, access issues (e.g. you need a page unpublished or deleted) — post in the #documentation Slack channel.

For help documenting a specific feature or module — go to the Slack channel or drupal.org issue queue for that feature. The people there are the subject matter experts. The documentation team can help you write well; they cannot substitute for the people who built the thing.

See also

• Content Style Guide
• README.md template for contrib modules
• Guidance on documenting contrib modules
• Core gatekeeper policy
• Source material: eojthebrave (Drupal documentation maintainer), issue #3581687