Documentation

Documentation on Drupal.org is a community-written wiki, which documents capabilities, design details, features, usage guidelines of Drupal core, and contributed projects.

All documentation is split by the major Drupal version into top-level guides: legacy Drupal 7 and current version of Drupal documentation.

There are also a few guides that live outside of the Documentation area, such as Drupal.org documentation, which is a documentation about the drupal.org website, as opposed to documentation about the Drupal software.

Writing and contributing documentation

First of all, thank you. Documentation is often overlooked, and yet crucial to development.

Second of all, you need to be a drupal.org confirmed user. If you are not, follow this guide.

Documentation is split into two content types. There's a Documentation Page and a Documentation Guide. This page you're currently reading is a documentation page - think of it as the place with all the real information, examples, code snippets, etc.

A documentation guide is a topic with a brief summary and list of links and summaries to more guides or pages. For example, the parent of this current page is a guide. You can view that here.

For style guides on both content types, visit this page.

Note: Even if you are a confirmed user, there may be some documentation where you do not have permission to edit or add to.

Editing existing documentation

To modify existing documentation, like this page, you have to click the green "edit" button to the right of the page title. You should then see a node edit page with fields like "title", "summary", "body" etc. You can edit the documentation page there.

Adding new documentation

First, you need to know whether you want to make a documentation guide or a documentation page. For example, if you visit the Drupal API documentation here, you'll note that it's a guide made up of other guides. Each API link, like Entity API or Layout API is a documentation guide and is then made up of 1 or more pages or even more guides.

So lets say the Form API didn't exist, and you wanted to make it. You would click the green down arrow next to the Drupal 11 APIs title, and click Add Guide.

First, check Documentation management if the page already exists, since it may already be created, but just not added in the menu.

Once you created the guide and wanted to add some content, you would navigate into the guide and again click the green down arrow and click Add Page. Now you can add the content, code examples, etc.

Note: When you add new guides or pages, it will create the node but not the menu link until it is approved by the current maintainer.

Legacy documentation

If you find legacy documentation that should be deleted, create an issue in the Documentation project describing which documentation should be deleted and why.

Maintaining documentation

All documentation is structured into guides. Each guide can have multiple 'maintainers'. Similar to project maintainers, these are the users who have additional permissions, and are responsible for the guide overall.

Maintainers can:

• create new pages, edit and delete any pages inside of the guide
• create new guides inside of the guide
• add or remove other maintainers
• modify guide menu, add, remove or edit menu items

Becoming a maintainer

Right now we are migrating the documentation into the new system, and are actively looking for maintainers. If you want to maintain a bit of documentation, sign up in the issue, or find the guide you are interested in, and use Discuss tab to show your interest.

If a documentation guide has no maintainers, and you are a confirmed user on Drupal.org, you can claim that guide by visiting the discuss page and clicking on the link which says "become a maintainer immediately."

First steps as a maintainer

An email will notify you, once you have been added as a maintainer of a guide. After that you will see a new 'Admin' menu item in the local tasks drop down. The admin area of the guide lets you manage content of the guide, modify menu, or add other maintainers.

Once you become a maintainer:

• Read through all pages inside of your guide
• Make sure all of them only cover a single Major version of Drupal (unless the topic of the guide is migration or comparison between versions, which is rare)
• Make sure all pages have short titles and descriptive summaries. Style guide has more details.
• Make sure the content on the pages is relevant to the topic of the guide, is concise, grammatically correct and well written.
• If there are multiple pages on the same topic in the guide, merge the content into a single page, with a table of contents and anchor links in the copy, and delete unneeded pages. (Such duplicate pages might appear when in the previous documentation system one of them was a 'parent' and the others were 'child' pages providing more info on the same topic, or duplicate pages were located in different parts ('books') of the documentation previously, and during migration they were collected into a single guide).
• If there is content that is not relevant to the topic of the guide or the Drupal version the guide covers, search for another guide in the documentation where this content might be relevant and move it there.
• If the page is quite long, add anchor links to the headings ('Anchor' button in WYSIWYG) and a table of contents at the top, linking to those headings. The page you are reading now is an example. 
• Review the guide page itself. Make sure the title is short, summary is descriptive, and description field has enough details. Style guide has more details.
• Make sure to remove 'Needs maintainers' status from the guide, unless you'd like to have some co-maintainers to help you.
• Review the guide and its contents overall. Is the topic properly covered? Is there any missing information? Any additional pages need to be written? Add missing information, and create new pages if needed.

Tip: some content in the guide might not be added to the menu. In which case you will only see it on the 'Manage content' page in the Admin area.

Guide maintainers are recommended to join the documentation group. This is a great place to ask questions and get feedback from other maintainers. As well as #documentation on Slack and #drupal-docs on IRC (possibly dead).

Managing content

You can manage content in your guide, including performing bulk operations, via 'Administer content' page. Click 'Admin' in the drop-down below 'Edit' and then pick 'Content'.

You will see all pages located inside of your guide, including unpublished ones and the ones not in the guide Menu.

To add new pages to the guide, use 'Add content' links at the bottom of the right sidebar on the guide page.

You can use Documentation management to search for relevant content among all pages.

Creating a sub-guide

All content on a single topic should be created as pages inside of the guide. You should only ever create a new guide, if there is a distinct topic, separate enough from your current guide, and there is enough content to justify a separate guide.

Use Documentation issue queue to discuss overall guides structure and propose new guides.

Managing menus

You can modify the list of items in the guide menu (displayed in the sidebar on inner pages and in the main area on the guide page itself), their order, and titles on the Menus page. Click 'Admin' in the drop-down below 'Edit' and then 'Menus'. Each guide has one default menu.

Managing maintainers

You can add co-maintainers to your guide by clicking 'Admin' - > 'Add people', and manage current co-maintainers on 'People' page ('Admin' -> 'People'). All maintainers have the exact same access to the guide administration, and can do the same changes you can.

If you are looking for co-maintainers, don't forget to edit your guide and set the status appropriately.

Comments

The purpose of the Discuss tab on a documentation page or a guide is to discuss improvements to the content of the page/guide. It is not a place to ask support questions or answer them.

If you see someone asking a support question on a documentation page/guide, do not answer the question and post the following:

Please don't ask support questions on documentation, Discuss tab is not meant for this. Ask them in https://www.drupal.org/forum or at https://drupal.stackexchange.com/ instead.

If you have access, unpublish the comments that include support questions anytime you see them on documentation pages.

Contributed projects documentation

Project maintainers can create documentation for their project in the documentation system. To do so:

1. If your project does not have documentation yet, go to the Contributed modules documentation guide. In the menu to the right of the Edit button, click Add guide.
2. Once the documentation is started, you can add a link to it on your project’s page. Edit your project page and go to the Resources vertical tab.
3. Fill out the Documentation title and URL, and save.

Migrating existing project documentation

If you already have documentation for your project, written using the old 'book page' legacy documentation content type, you can migrate it into the new system. To do so, find your pages (probably in the old Site Building Guide), and follow the instructions in the Migrating legacy documentation section above.