The reason for the ‘Content Type’ in the title is that this document relates to Drupal Content Types (https://www.drupal.org/docs/7/understanding-drupal/content-types) which are blueprints for content items such as news articles, blog entries, etc within the Drupal CMS.
The CTD is the blueprint for these Content Types, detailing each element, property and their expected DataType.
TL;DR: Its really good and you can see an example here: https://docs.google.com/spreadsheets/d/1-rtfgQT4M1ptDWsM8h2V4tiz4auJkGnv7UhJInLCZgg/edit#gid=0
Why create this document? That’s a good question. No one wants MORE documentation to write and maintain. We’ll take each reason one at a time below.
Nitty gritty detail
In a lot of specifications for Drupal or other CMS based websites there will be some kind of table like this:
||Required, 255 characters
This is great for agreeing the high level detail of each Content Type and how each field should behave, but it lacks the minute detail that a developer needs to create these fields.
For example on the Body field, should that have a WYSIWYG editor? What options should be available? Should the field allow/not allow certain tags like <script>? The list goes on.
Compare that to the following example from the CTD:
Don’t worry about knowing what all the columns mean, we’ll cover that below. It’s clear that this example is providing much more detail than our table above. For example we know that we are using a WYSIWYG editor and which tags are allowed and we have some help text for content editors.
This takes the guesswork out of creating these fields allowing the developer to crack on without worrying about the exact wording of the help text for example.
When working with Drupal where multiple developers are creating Content Types and populating fields there is the risk that duplicate fields will be created.
Take for example two developers Tim and Tom. Both are creating a title field for their respective Content Types. In the worst case scenario we would end up with two fields `page_title` and `news_title` which are exactly the same field.
In Drupal we can share fields across entities so it makes sense to have one `title` which is shared across all Content Types that have a title.
In the CTD there is a machine name column:
This is the unique identifier for this field across the site. Now when Tim and Tom create their Content Types they can use the shared title field.
This is one of the great strengths of the CTD. Mapping out all the fields we can easily see which ones are the same and can be reused across the site. This cuts down development time and unnecessary duplication.
This document isn’t just for developers. This is a useful tool for clients too.
Presenting this document to the client can be daunting for everyone but the benefit is that assumptions are ironed out early and the client can start thinking about how they want the fields to behave and the help text they want.
A good example is the WYSIWYG editor for the body field. The options and restrictions can be agreed before development starts which saves wasted effort down the line.
Client content planning
Lastly presenting this document to the client allows them to plan their content more effectively. Most big Drupal sites now use the Paragraphs (https://www.drupal.org/project/paragraphs) module to provide content editors with flexibility.
Showing the client which Paragraphs they will have available on each Content Type and what fields those Paragraphs will have allows them to start thinking about how they will model their content.