Imagine finding a beautifully built tool in someone's garage with no label, no instructions, and no idea what it's for — you'd probably leave it exactly where it was. A Drupal module without a README is that unlabeled tool: the code might be excellent, but nobody will trust it enough to install it. A README.md isn't documentation you write after the "real work" is done — it's the first (and sometimes only) thing a stranger reads before deciding whether your module solves their problem.
What you'll learn in this lesson
- The sections Drupal.org's own project page and community expect in a README
- Why "what it does" and "how to install it" need to come before anything else
- How to document configuration and usage so a stranger doesn't need to read your source code
- What belongs in a README versus what belongs in inline code documentation
The sections a real README needs
The Examples project's own top-level README (the same module you've been reading source from throughout this course) is a genuinely good model to follow — it opens with project links, then a plain-English "What Is This?" section, then "How To Use," then "How To Install." That order isn't arbitrary: readers scan top to bottom deciding "is this relevant to me" before they ever get to "how do I set it up."
# Module Name
## Introduction
A short, honest paragraph: what does this module actually do, and why
would someone install it instead of an existing contrib module?
## Requirements
- Drupal core version required
- Any contrib modules this depends on
## Installation
Install as you would normally install a contributed Drupal module. See:
https://www.drupal.org/docs/extending-drupal/installing-modules
## Configuration
Where to find this module's settings, and what each option controls.
## Maintainers
Current maintainers for this project:
- Your Name (your-drupal-org-username)This is the same skeleton Drupal.org's own module-page templates expect, which is why following it closely makes your project page look complete rather than half-finished the moment it's approved.
"What it does" earns the reader's next ten seconds
The single most common README mistake is starting with installation instructions before explaining what the module is for. Someone landing on your project page from a search result doesn't yet know if they want to install anything — they're deciding whether to keep reading. A concrete, specific opening sentence ("Provides a queue-backed worker for processing bulk CSV imports without blocking the request") earns their attention far better than a vague one ("Adds import functionality to Drupal").
Document configuration like the reader has never seen your admin form
Because they haven't. If your module adds a settings page at /admin/config/my-module/settings, say so explicitly, and explain what each meaningful option controls — not just its label, but what changing it actually does. This is the section people come back to months later when they've forgotten how their own site is configured; write it for that future reader, not just the first-time installer.
See it for yourself
Open the Examples project's own top-level README.md in the module you've been reading from all course — notice it explicitly tells you three different ways to interact with the examples (enable and use them, read the code, browse the API documentation site) before it ever gets to installation steps. That ordering is deliberate, and it's the same instinct worth applying to your own module's README.
Quick check: your module has a genuinely useful settings page, but your README jumps straight from "Installation" to "Maintainers" with nothing in between. What's the practical cost of that gap? Every future user (including future-you) has to open the settings form and guess what each field does, rather than reading a one-paragraph explanation that would have taken five minutes to write.
Key takeaways
- Follow the standard README skeleton — Introduction, Requirements, Installation, Configuration, Maintainers — the same shape Drupal.org's own templates and the Examples project itself use.
- Lead with a specific, concrete sentence about what the module does — vague openings lose a reader's attention before they reach the installation steps.
- Document what each configuration option actually controls, not just its label — write for the user who forgot how their own site is set up.
- Keep implementation detail (design patterns, class internals) out of the README — that belongs in code docblocks and `hook_help()`, aimed at a different audience.
Coming up next
A great README still won't save a user whose site breaks because your module silently assumed a dependency that wasn't there. Next, you'll learn how to declare your module's dependencies properly so Drupal — not your users — catches a missing requirement before anything breaks.