diff --git a/docs/designers-developers/faq.md b/docs/designers-developers/faq.md
index dc1ae26b8b844..4e46b47ab7729 100644
--- a/docs/designers-developers/faq.md
+++ b/docs/designers-developers/faq.md
@@ -1,10 +1,10 @@
# Frequently Asked Questions
-This initial set of questions was created when the Gutenberg project was relatively new, for a more recent set of questions, please see Matt's November 2018 post [WordPress 5.0: A Gutenberg FAQ](https://ma.tt/2018/11/a-gutenberg-faq/).
+What follows is a set of questions that have come up from the last few years of Gutenberg development. If you have any questions you’d like to have answered and included here, [just open up a GitHub issue](https://github.com/WordPress/gutenberg/issues) with your question. We’d love the chance to answer and provide clarity to questions we might not have thought to answer. For a look back historically, please see Matt's November 2018 post [WordPress 5.0: A Gutenberg FAQ](https://ma.tt/2018/11/a-gutenberg-faq/).
## What is Gutenberg?
-“Gutenberg” is the name of the project to create a new editor experience for WordPress. The goal is to create a new post and page editing experience that makes it easy for anyone to create rich post layouts. This was the kickoff goal:
+“Gutenberg” is the name of the project to create a new editor experience for WordPress — contributors have been working on it since January 2017 and it’s one of the most significant changes to WordPress in years. It’s built on the idea of using “blocks” to write and design posts and pages. This will serve as the foundation for future improvements to WordPress, including blocks as a way not just to design posts and pages, but also entire sites. The overall goal is to simplify the first-time user experience of WordPress — for those who are writing, editing, publishing, and designing web pages. The editing experience is intended to give users a better visual representation of what their post or page will look like when they hit publish. Originally, this was the kickoff goal:
> The editor will endeavour to create a new page and post building experience that makes writing rich posts effortless, and has “blocks” to make it easy what today might take shortcodes, custom HTML, or “mystery meat” embed discovery.
@@ -14,13 +14,16 @@ Key takeaways include the following points:
- By embracing blocks as an interaction paradigm, we can unify multiple different interfaces into one. Instead of learning how to write shortcodes and custom HTML, or pasting URLs to embed media, there's a common, reliable flow for inserting any kind of content.
- “Mystery meat” refers to hidden features in software, features that you have to discover. WordPress already supports a large number of blocks and 30+ embeds, so let's surface them.
-Gutenberg is being developed on [GitHub](https://github.com/WordPress/gutenberg) under the WordPress organization, and you can use it today — [available in the plugin repository](https://wordpress.org/plugins/gutenberg/).
+Gutenberg is developed on [GitHub](https://github.com/WordPress/gutenberg) under the WordPress organization. The block editor has been available in core WordPress since 5.0. If you want to test upcoming features from Gutenberg project, it is [available in the plugin repository](https://wordpress.org/plugins/gutenberg/).
-## When will Gutenberg be merged into WordPress?
+## What’s on the roadmap long term?
-Gutenberg was merged into [WordPress 5.0](https://wordpress.org/news/2018/12/bebo/) that was released in December 2018.
+There are four phases of Gutenberg which you can see on the [official WordPress roadmap](https://wordpress.org/about/roadmap/). As of writing this, we’re currently in phase 2:
-The editor focus started in early 2017 with the first three months spent designing, planning, prototyping, and testing prototypes, to help us inform how to approach this project. The actual plugin, which you can install from the repository, was launched during WordCamp Europe in June.
+1. Easier Editing — Already available in WordPress since 5.0, with ongoing improvements.
+2. Customization — Full Site editing, Block Patterns, Block Directory, Block based themes.
+3. Collaboration — A more intuitive way to co-author content
+4. Multi-lingual — Core implementation for Multi-lingual sites
## What are “blocks” and why are we using them?
@@ -35,11 +38,30 @@ The current WordPress editor is an open text window—it’s always been a wonde
As we thought about these uses and how to make them obvious and consistent, we began to embrace the concept of “blocks.” All of the above items could be blocks: easy to search and understand, and easy to dynamically shift around the page. The block concept is very powerful, and if designed thoughtfully, can offer an outstanding editing and publishing experience.
-## What is the writing experience like?
+## When was Gutenberg started?
+
+The editor focus started in early 2017 with the first three months spent designing, planning, prototyping, and testing prototypes, to help us inform how to approach this project. The first plugin was launched during WordCamp Europe in June 2017.
+
+## When was Gutenberg merged into WordPress?
+
+Gutenberg was first merged into [WordPress 5.0](https://wordpress.org/news/2018/12/bebo/) in December 2018. See [the versions in WordPress page](https://developer.wordpress.org/block-editor/principles/versions-in-wordpress/) for a complete list of Gutenberg plugin versions merged into WordPress core releases.
+
+## What are “blocks” and why are we using them?
+
+The classic WordPress editor is an open text window—it’s always been a wonderful blank canvas for writing, but when it comes to building posts and pages with images, multimedia, embedded content from social media, polls, and other elements, it required a mix of different approaches that were not always intuitive:
+
+- Media library/HTML for images, multimedia and approved files.
+- Pasted links for embeds.
+- Shortcodes for specialized assets from plugins.
+- Featured images for the image at the top of a post or page.
+- Excerpts for subheadings.
+- Widgets for content on the side of a page.
+
+As we thought about these uses and how to make them obvious and consistent, we began to embrace the concept of “blocks.” All of the above items could be blocks: easy to search and understand, and easy to dynamically shift around the page. The block concept is very powerful, and when designed thoughtfully, can offer an outstanding editing and publishing experience. Ultimately, the idea with blocks is to create a new common language across WordPress, a new way to connect users to plugins, and replace a number of older content types — things like shortcodes and widgets — that one usually has to be well-versed in the idiosyncrasies of WordPress to understand.
-Our goal with Gutenberg is not just to create a seamless post- and page-building experience. We also want to ensure that it provides a seamless writing experience. Though individual paragraphs of text become their own “blocks,” the creation and editing of these blocks are being designed in a way that could be just as simple—if not more so—than the current WordPress editor experience. Here is a brief animation illustrating the Gutenberg writing experience:
+## What is the writing experience like?
-
+Our goal with Gutenberg is not just to create a seamless post- and page-building experience. We also want to ensure that it provides a seamless writing experience. To test this out yourself, [head to this demo and give it a try](https://wordpress.org/gutenberg/)!
## Are there Keyboard Shortcuts for Gutenberg?
@@ -91,7 +113,7 @@ This is the canonical list of keyboard shortcuts:
| ⌃⌥O |
- | Navigate to a the next part of the editor. |
+ Navigate to the next part of the editor. |
Ctrl+` |
⌃` |
@@ -101,7 +123,7 @@ This is the canonical list of keyboard shortcuts:
⌃⇧` |
- | Navigate to a the next part of the editor (alternative). |
+ Navigate to the next part of the editor (alternative). |
Ctrl+Alt+N |
⌃⌥N |
@@ -120,6 +142,11 @@ This is the canonical list of keyboard shortcuts:
Ctrl+Shift+Alt+M |
⇧⌥⌘M |
+
+ | Toggle fullscreen mode. |
+ CMD+Option+Shift+F |
+ ⇧⌥⌘F |
+
@@ -193,6 +220,11 @@ This is the canonical list of keyboard shortcuts:
/ |
/ |
+
+ | Remove multiple selected blocks. |
+ |
+ delbackspace |
+
@@ -247,7 +279,7 @@ This is the canonical list of keyboard shortcuts:
Here is a brief animation illustrating how to find and use the keyboard shortcuts:
-
+
## Is Gutenberg built on top of TinyMCE?
@@ -261,7 +293,7 @@ Our [list of supported browsers can be found in the Make WordPress handbook](htt
## How do I make my own block?
-The API for creating blocks is a crucial aspect of the project. We are working on improved documentation and tutorials. Check out the [Creating Block Types](/docs/designers-developers/developers/tutorials/block-tutorial/readme.md) section to get started.
+The best place to start is the [Create a Block Tutorial](https://developer.wordpress.org/block-editor/tutorials/create-block/).
## Does Gutenberg involve editing posts/pages in the front-end?
@@ -269,13 +301,11 @@ No, we are designing Gutenberg primarily as a replacement for the post and page
## Given Gutenberg is built in JavaScript, how do old meta boxes (PHP) work?
-We plan to continue supporting existing meta boxes while providing new ways to extend the interface.
-
-*See:* [Pull request #2804](https://github.com/WordPress/gutenberg/pull/2804)
+See the [Meta Box Tutorial](https://developer.wordpress.org/block-editor/tutorials/metabox/) for more information on using Meta boxes with the new block editor.
## How can plugins extend the Gutenberg UI?
-The main extension point we want to emphasize is creating new blocks. We are still working on how to extend the rest of the UI that is built in JS. We are tracking it here: [Issue #1352](https://github.com/WordPress/gutenberg/issues/1352)
+The main extension point we want to emphasize is creating new blocks. Blocks are added to the block editor using plugins, see the [Create a Block Tutorial](https://developer.wordpress.org/block-editor/tutorials/create-block/) to get started.
## Are Custom Post Types still supported?
@@ -287,7 +317,7 @@ Yes, a columns block is available in Gutenberg.
## Does Gutenberg support nested blocks?
-Yes, it is supported. You can have multiple levels of nesting – blocks within blocks within blocks.
+Yes, it is supported. You can have multiple levels of nesting – blocks within blocks within blocks. See the [Nested Block Tutorial](https://developer.wordpress.org/block-editor/tutorials/block-tutorial/nested-blocks-inner-blocks/) for more information.
## Does drag and drop work for rearranging blocks?
@@ -303,7 +333,7 @@ Blocks are able to provide base structural CSS styles, and themes can add styles
Other features, like the new _wide_ and _full-wide_ alignment options, are simply CSS classes applied to blocks that offer this alignment. We are looking at how a theme can opt in to this feature, for example using `add_theme_support`.
-*See:* [Theme Support](/docs/designers-developers/developers/themes/theme-support.md)
+This is currently a work in progress and we recommend reviewing the [block based theme documentation](https://developer.wordpress.org/block-editor/tutorials/block-based-themes/) to learn more.
## How do editor styles work?
@@ -337,7 +367,7 @@ There is also the [Classic Editor plugin](https://wordpress.org/plugins/classic-
Custom TinyMCE buttons still work in the “Classic” block, which is a block version of the classic editor you know today.
-(Gutenberg comes with a new universal inserter tool, which gives you access to every block available, searchable, sorted by recency and categories. This inserter tool levels the playing field for every plugin that adds content to the editor, and provides a single interface to learn how to use.)
+Gutenberg comes with a new universal inserter tool, which gives you access to every block available, searchable, sorted by recency and categories. This inserter tool levels the playing field for every plugin that adds content to the editor, and provides a single interface to learn how to use.
## How do shortcodes work in Gutenberg?
@@ -347,11 +377,17 @@ However we see the block as an evolution of the `[shortcode]`. Instead of having
## Should I move shortcodes to content blocks?
-We think so. Blocks are designed to be visually representative of the final look, and they will likely become the expected way in which users will discover and insert content in WordPress.
+We think so for a variety of reasons including but not limited to:
+
+- Blocks have visual editing built-in which creates a more rich, dynamic experience for building your site.
+- Blocks are simply html and don’t persist things the browser doesn't understand on the frontend. In comparison, if you disable a plugin that powers a shortcode, you end up with strange visuals on the frontend (often just showing the shortcode in plain text).
+- Blocks will be discovered more readily with the launch of the block directory in a way shortcodes never could be allowing for more people to get more functionality.
+
+Ultimately, Blocks are designed to be visually representative of the final look, and, with the launch of the Block Directory in 5.5, they will become the expected way in which users will discover and insert content in WordPress.
## Is Gutenberg made to be properly accessible?
-Accessibility is not an afterthought. Not every aspect of Gutenberg is accessible at the moment. You can check logged issues [here](https://github.com/WordPress/gutenberg/labels/Accessibility). We understand that WordPress is for everyone, and that accessibility is about inclusion. This is a key value for us.
+Accessibility is not an afterthought. Not every aspect of Gutenberg is accessible at the moment. You can check logged issues [here](https://github.com/WordPress/gutenberg/labels/Accessibility%20%28a11y%29). We understand that WordPress is for everyone, and that accessibility is about inclusion. This is a key value for us.
If you would like to contribute to the accessibility of Gutenberg, we can always use more people to test and contribute.
@@ -376,17 +412,6 @@ In PHP:
$blocks = parse_blocks( $post_content );
```
-## Why should I start using this once released?
-Blocks are likely to become the main way users interact with content. Users are going to be discovering functionality in the new universal inserter tool, with a richer block interface that provides more layout opportunities.
-
-## What features will be available at launch? What does the post-launch roadmap look like?
-As part of the focus on the editor in 2017, a focus on customization and sitebuilding is next. From [the kickoff post](https://make.wordpress.org/core/2017/01/04/focus-tech-and-design-leads/):
-
-> The customizer will help out the editor at first, then shift to bring those fundamental building blocks into something that could allow customization “outside of the box” of post_content, including sidebars and possibly even an entire theme.
-
-With the editor, we lay the foundation for bigger things when it comes to page building and customization.
-
-A lot of features are planned, too many to list here. You can check [Gutenberg's roadmap](https://github.com/WordPress/gutenberg/blob/master/docs/roadmap.md) for more details.
-
## WordPress is already the world's most popular publishing platform. Why change the editor at all?
-As an open-source project, we believe that it is critical for WordPress to continue to innovate and keep working to make the core experience intuitive and enjoyable for all users. As a community project, Gutenberg has the potential to do just that, and we're excited to pursue this goal together. If you'd like to test, contribute, or offer feedback, [we welcome it here](http://wordpressdotorg.polldaddy.com/s/gutenberg-support).
+
+The Editor is where most of the action happens in WordPress’s daily use, and it was a place where we could polish and perfect the block experience in a contained environment. Further, as an open-source project, we believe that it is critical for WordPress to continue to innovate and keep working to make the core experience intuitive and enjoyable for all users. As a community project, Gutenberg has the potential to do just that, and we’re excited to pursue this goal together. If you’d like to test, contribute, or offer feedback, we welcome you to [share what you find on GitHub](https://github.com/WordPress/gutenberg/issues).