Mid-to-longform content
Structural (group) content types

Mid-to-longform content

Post

An article or extended announcement that explains something happening in Drupal.

Format: HTML
Title: 60 characters or less
Summary: 140 characters or less
Body: 250-1,500 words

Documentation page

A wiki-like article documenting capabilities, design details, features, usage guidelines, etc., of Drupal core or contributed projects.

Format: HTML

Title: 60 characters or less
Keep the title as short as possible. You can use Summary field to give more information about the contents of the page. The summary will be displayed alongside title in most cases.

Summary: 140 characters or less
A concise summary of the whole article. This is used in documentation listings, page meta-tags, search results snippets.

Body: 300-1,500 words

  • Be concise. Think about your target audience and write in a way that will be understandable and useful for them. Too many words are often not helpful.
  • Use code examples.
  • Use headings and lists to break the text in chunks and make it more readable.
  • All documentation is split per Major version. Thus each documentation page should only contain content relevant to a single Major version of Drupal (unless the topic is migration or comparison between versions). If you want to provide information about the same topic for multiple major versions - create a page in relevant guides for each version and link them together via 'Related content' tag.
  • Information for different Minor versions can be present on the same page. The default version of the narrative should always be the latest available version, with differences in previous Minor versions clearly highlighted in the body via use of headings.

Tags: 4-5 tags or less
Only use major concepts that cover the main topic of the article. These will help users find content on similar topic.
Examples of good tags: 'usability', 'accessibility', 'configuration management'.
Examples of bad tags: 'add', 'module', 'view', 'feature'.

Related content: up to 8 related content pieces
This is an entity reference field, which enables the connection between this page and the content topically related to it. This can be a page on the same topic for another Major version of Drupal, or a relevant page in contributed project documentation, a relevant change record, blog post, or a general page. Do not add the pages from the same guide as Related content.

Guide: single value only
This is a parent guide for the documentation page.

Status: single value only
By default all documentation pages have no status. If you find a problem with the page, you can mark it as either Incomplete, Out of date or Deprecated. Make sure to explain what needs to happen in order to solve the problem and remove the status.

URL path settings: automated.
URL aliases are being generated automatically for all documentation pages. Do not change them. Do not create custom top-level aliases, this will break the information architecture of the section.

Structural (group) content types

Structural content types are used to organize content, provide structure, permissions, and enable maintainership. They are not used to create content itself, e.g. explain a topic or announce news.

Documentation guide

A collection of documentation pages about specific topic with dedicated maintainers.

A guide should only include content related to a single Major version of Drupal, but multiple Minor versions.

Title: 60 characters or less
Keep the title as short as possible. You can use Summary field to give more information about the contents of the guide. The summary will be displayed alongside title in most cases.

Summary: 140 characters or less
A concise summary of the content in the guide. This is used in documentation listings, page meta-tags, search results snippets, etc.

Description: 10-100 words
A description of the contents of the guide, a bit more detailed than the Summary. This will be displayed at the top of the guide page, while Summary field will not. This should NOT be a documentation content, but a description of the content that can be found inside of the guide.

Tags: 4-5 tags or less
Only use major concepts that cover the main topic of the article. These will help users find content on similar topic.
Examples of good tags: 'usability', 'accessibility', 'configuration management'.
Examples of bad tags: 'add', 'module', 'view', 'feature'.

Related content: up to 8 related content pieces
This is an entity reference field, which enables the connection between this guide and the content topically related to it. This can be a guide on the same topic for another Major version of Drupal, or a relevant guide in contributed project documentation, a relevant change record, blog post, or a general page. Do not add the pages from the guide itself as Related content.

Guide: single value only.
This is a parent guide for the current guide.

A guide can only be created inside of one of the top level guides such as 'Drupal 7', 'Drupal 8', or 'Drupal.org'. If there is a need for another top level guide, open an issue in the Documentation queue and the Drupal Association staff will review the request and create a guide if it matches the intended information architected of the Documentation area.

Status: single value only
By default all documentation guides have no status. A guide maintainer can mark the guide as 'Seeking co-maintainer(s)' to find some help or 'Needs maintainers' to find someone else to maintain the guide.

URL path settings: automated.
URL aliases are being generated automatically for all documentation pages. Do not change them. Do not create custom top-level aliases, this will break the information architecture of the section.