Write Layout Builder handbook documentation

At least mention this contrib module (if only to spare the regulars on the Slack channel from repeatedly answering the same question): Layout Builder Restrictions

I have created the start to the page: https://www.drupal.org/docs/8/core/modules/experimental-layout-builder

I made some stub pages.

Tagging for upcoming collaboration days.

I added a child page, https://www.drupal.org/docs/8/core/modules/layout-builder/additional-mod..., in response to my comment in #10. I guess that @tedbow is the only one with access to add it to the menu.

Here's the structure I currently have in mind for the documentation. I can move this to the issue summary once there's been an opportunity for users to weigh in and point out items that should be added or removed. Items without @todo already exist in the documentation.

Layout Builder overview

• @todo summarize what Layout Builder is capable of
• @todo *briefly* describe how it can be used in a default or override context, include links to the "Creating Layout Defaults" and
  "Creating Layout Overrides" pages in this handbook for more details.
• @todo *briefly* describe inline block functionality, can link to more detailed coverage of this topic in the "Building Layouts Using The
  Layout Builder UI" page.

Creating Layout defaults

• Layout Defaults in Layout Builder (summarizes what they are and their specificity)
• Example: Creating a Layout Default for the Article content type

Creating Layout Overrides

• Layout Overrides in Layout Builder (explanation)
• Example: Creating a Layout Override for an Article Node

Building Layouts Using the Layout Builder UI

• Accessing the Layout Builder UI
• Example: Building a Page Layout in Layout Builder
  • Adding Sections
  • Add content (Blocks) section incomplete
• @todo Editing existing Layouts
  • @todo Moving blocks
  • @todo Cancelling Changes and reverting to defaults

Additional modules

• Layout Builder Restrictions

Theming and Extending

• @todo add section on adding custom layouts
• @todo add section on theming

I think that's a totally fine organization; thanks @bnjmnm!

(Small content style note: our docs standards specify using sentence-case for handbook page titles. So "Theming and extending" rather than "Theming and Extending", etc. "Layout Builder overrides" is correct because "Layout Builder" is a proper noun.)

Marking as "needs work" to indicate that there's stuff there already. And quite good stuff, too! Assigning to myself to work on this awhile.

Updating the issue summary a bit, including with the contents of #19, I'll get specific feedback from the #documentation folks, too.

First order of business:

https://www.drupal.org/docs/8/core/modules/layout-builder
"Layout Builder provides layout building utility for managing the display of all fieldable entities on a site."

Glarby flarby blergen flerg? :)

How about:

"Layout Builder provides an easy-to-use page builder for site builders and content authors to create layouts to templated content (e.g. all articles) or one-off content (e.g. a single About Us page)."

...or something more "human friendly." :) (Set it to that; we can further refine and/or revert the revision if you disagree.)

Filled out the stub page at https://www.drupal.org/docs/8/core/modules/layout-builder/layout-builder... with some actual text. Copy/pasted some of the text from https://dri.es/why-drupal-layout-builder-is-so-unique-and-powerful as a starting point. We will probably want a screenshot or two on this page as well, but probably best to wait until things are pinned down.

And adjusting issue summary to that effect...

Ooof. More of this "entities, instances, bundles... oh my!" speak at https://www.drupal.org/docs/8/core/modules/layout-builder/creating-layou....

This is important information, for people who understand how Drupal's underpinnings work. However, this interface is largely targeted at people who do not. So I feel like maybe we should create a separate page, or sub-section on each of these pages, like "For techies" or "Under the hood" or something.

For now, I changed:

Layout Defaults in Layout Builder
Layout Defaults are Page Layouts that apply to all non-overridden instances of an entity.

The specificity of a Layout Default depends on the entity type it is used with:

For entity types that use bundles, Layout Defaults are created on a per bundle basis. For example: A layout default would be created for the Article bundle (AKA content type) of the Node entity type, or a layout default would be created for the Tags bundle (AKA Vocabulary) of the Taxonomy entity type.
For entity types that do not use bundles, such as User, the Layout Defaults are created for all non-overridden instances of that entity type.
Whether or not an entity type uses bundles, Layout Defaults are applied on a per-view-mode basis. This means Layout Builder can be used on some view modes but not others. It also means different view modes can use different Layout Defaults - for example  the “Teaser” view mode for a content type can use a different Layout Default from its default view mode.

To:

Layout Defaults in Layout Builder
Layout Defaults are Page Layouts that will be used as long as no layout overrides exist. The specificity of the layout will depend on the piece of content it's applied to:

Some entity types, such as Content Types and Vocabularies, have "sub-types" attached (known as "bundles" under the hood) (e.g. "Articles" or "Blog posts" in the case of Content types; "Tags" or "Categories" in the case of Vocabularies). In this case, default layouts apply to all content of that specific sub-type (e.g. a layout default for Article applies to all Articles on the site, but not to Blog posts).
Other entity types do not have sub-types, such as Users. In this case, layouts will apply across the board, unless otherwise overridden.
Layout defaults are also applied on a "per-view-mode" basis (a view mode specifies a different context in which a piece of content may be displayed, such as Search results or Teaser). This means Layout Builder can be used on some but not others, and that different view modes can use different Layout Defaults - for example  the “Teaser” view mode for a content type can use a different Layout Default from its default view mode.

This is still a lot more "in the weeds" than I would otherwise like (we try and avoid using "entity" in documentation, and the "Anglicization" also contains controversial language like "sub-type" — eep!); however, I can see why it's important to understand these concepts because otherwise it's rife for confusion about "Yo! Why did my layout not show up?!"

Skipping around a bit, https://www.drupal.org/docs/8/core/modules/layout-builder/additional-mod... looks good. I added some descriptions to those modules, copy/pasta/modified from the project pages.

Though one thing of note is https://www.drupal.org/project/layout_builder_modal is not covered by the sec. team so I'm not sure if we want to recommend it in "official" docs.

Put some actual content at https://www.drupal.org/docs/8/core/modules/layout-builder/theming-and-ex... too, linking it to https://www.drupal.org/docs/8/api/layout-api which I just learned exists. (Thanks, @tim.plunkett!) The theming part is wayyy above my pay grade, however, and also (according to the team) not actually writable yet while things are still in flux.

Updating issue summary.

Ok, out of steam for now.

Basically, I'd like to talk more about what level of sausage factory we're exposing here, and/or who the target audience of these docs are, and see if we can negotiate something sensible there.

Also, I spoke with @jhodgdon in the #documentation channel, and she pointed out that:

Yeah, I wouldn't worry about getting the docs done until after the module has stabilized. Consider marking the stub page(s) as Incomplete and putting a note at the top that the docs are coming soon.

and also...

You could write Help Topics! :)

Which is a great idea for 8.8. :)

But since this is not part of the docs gate, removing that inference in the issue summary, and also removing the tag. This still remains a priority for the team, but it makes more sense to drill on it after we (hopefully) manage to make the module stable in time for 8.7. (Or in any event, after the UI is locked down.)

Very pleased that @webchick honed in on exactly the areas that I was concerned about. "Glarby flarby blergen flerg" is a pretty apt description for some of the things I could't quite articulate my reservations about 🙂  

I re-rewrote Angie's introductory blurb at https://www.drupal.org/docs/8/core/modules/layout-builder with something I felt was a bit more humane and introductory-user-friendly:

Drupal 8's Layout Builder allows content editors and site builders to easily and quickly create visual layouts for displaying content. Users can customize how content is arranged on a single page, or across types of content, or even create custom landing pages with an easy to use drag-and-drop interface.

Explore the sections below to find out how to get started with Layout Builder and how to apply it to templated types of content.

I understand that this tone and voice is a bit more personal/less explicitly developer-centric than pretty much every other core module meta-page, but to quote Muad'dib when he first met Liet-Kynes... "It seemed the right thing to do."

If that sort of voice is okay, I'm happy to expand it to the rest of the Layout Builder docs.

@eatings, as someone who wrote many of the initial drafts of the Layout Builder documentation, I fully support your efforts in making it friendlier and more human readable. It's difficult to write properly-empathetic user-friendly documentation for something we spend 50+ hrs a week building. I'm very pleased you're interested in expanding on this.

The only place that would ever be of concern is if it removes important technical details. I certain they can coexist happilyl I'll keep an eye on the changes and chime in if this happens to come up. You are also welcome to ask questions in this issue or directly message me in Drupal slack if you'd like clarification on how something works before you write about it. I'm pleased with how approachable the Layout Builder UI is, and similarly pleased that there is interest in making the documentation friendlier as well.