From 3b4d8ce127e86b130e058a0d7687bc827a2363fb Mon Sep 17 00:00:00 2001 From: Darren Ethier Date: Mon, 19 Apr 2021 09:44:38 -0400 Subject: [PATCH 01/13] add doc on Gutenberg Principles --- docs/README.md | 3 + docs/explanations/principles.md | 106 ++++++++++++++++++++++++++++++++ 2 files changed, 109 insertions(+) create mode 100644 docs/explanations/principles.md diff --git a/docs/README.md b/docs/README.md index 8da0f469ae3122..8b482ee47c249a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -20,6 +20,9 @@ The Editor offers rich new value to users with visual, drag-and-drop creation to ## Quick links +### Gutenberg Principles +[The Gutenberg principles document](/docs/explanations/principles.md) highlights a few principles that are guiding the overall project and shape various development and design decisions. + ### Create a Block Tutorial [Learn how to create your first block](/docs/getting-started/tutorials/create-block/README.md) for the WordPress block editor. From setting up your development environment, tools, and getting comfortable with the new development model, this tutorial covers all what you need to know to get started with the block editor. diff --git a/docs/explanations/principles.md b/docs/explanations/principles.md new file mode 100644 index 00000000000000..754a57527451fc --- /dev/null +++ b/docs/explanations/principles.md @@ -0,0 +1,106 @@ + + +# Gutenberg Principles + +This document has been written so that those contributing to the Gutenberg project can have some understanding of what guides decisions around what is included in the project (or not). + +An important thing to keep at top of mind when reviewing these principles is that they are not isolated from each other. There is a cohesiveness and complementary nature between them that results in a synergistic impact and direction. + +When applied, sometimes these principles build on each other much like the idea of constructing a house with a foundation, walls and roof. However, other times the application of the principles results in something that is more similar to a tapestry where threads of each principle are embedded together and evident in the finished feature or design of the project. + + +## Aim for delightful, consistent, accessible user interfaces for empowering content creation and expression. + +_“Optimize for the user” (Matias - [Gutenberg or the Ship of Theseus](https://matiasventura.com/post/gutenberg-or-the-ship-of-theseus/))_ + +Each of the words in this principle are deliberate: + + +### Delightful + +The user interfaces should “get out of the way” and support the user in creating their content. They should lead to experiences where the user (in the vernacular of Marie Kondo) _finds delight_ with each new thing they discover they can do or accomplish. + + +### Consistent + +Any interfaces are consistently applied. Users should be able to _rely on muscle memory and learned patterns_ as they become familiar with how it works. + +This also applies to learning _where to find_ different elements that the user might interact with in creating their content. + + +### Accessible + +Being accessible is a holistic principle that embraces not only the desire that _everyone can work with Gutenberg interfaces no matter their ability_ but also that the improvements made are _equitable_ and improve the experience for _every_ user. This is a lofty challenge and definitely hard balance to get right - but already there is fruit being born in the improvements that have been made to the user interface over the last few years. + +Modern web application development brings its own set of accessibility problems around standards and consistent application between browsers which often requires some unique solutions that might not be apparent on the first attempt. So we acknowledge that accessibility is not something that can be implemented statically but instead is an ongoing part of the interface creation and refinement. + + +### Empowering + +With delightful, consistent, and accessible interfaces we are aiming for empowering users to try and do things that they assumed were beyond their capabilities and reach before. We strive for those “Aha” moments of surprise and wonder as folks discover how they can unleash their creativity. + +Example: https://twitter.com/colemank83/status/1371846826664591364 + + +## Curated Extensibility + +The use of the word _curated_ expressly refers to implementing extensibility in a way that prioritizes those _using Gutenberg interfaces to create their content_ over developers integrating with the system. As a result, every extensibility interface request is filtered through the question of how it impacts creator workflows. + +Implementation details are ephemeral. Practically this means that the traditional WP approach of wrapping things in filters and liberal use of actions is avoided in favor of explicit extension interfaces that expose _functionality_ but hide the _implementation details._ Gutenberg has opinionated APIs that favor stability and functionality for the user over flexibility for the developer. + +Extensibility interfaces in Gutenberg favor: + +**Modularity** - the concept of being able to combine blocks or components into different types of layout or content (see “[Embrace the modularity](https://riad.blog/2020/01/28/embrace-the-modularity/)”). + +**Encapsulation** - there are appropriate error handling and boundaries around things that could be broken by things extending the interface. + +**Experimentation** - Often new APIs and interfaces clearly start as experimental while reliability and usability of different approaches are being tested. These experiments always begin with determining what problem is solved from the _creator_ perspective and seek to validate how it impacts the user workflow. The intent is to explore what generalizations of the creator's use-case are possible and to discover better abstractions before solidifying around the contract exposed to extension developers. + + +## Progressive Complexity + +_“On the Layers of the Onion”_ (Matias - Gutenberg or the Ship of Theseus) + +There are two perspectives for this principle: + +As it applies to **developers** (plugin or theme), progressive complexity means that there are degrees of ability and understanding needed in order to extend or contribute to Gutenberg. This has overlap with the _curated extensibility_ principle where some interfaces have clearly defined (opinionated) registration APIs that hide much of the complexity in the lower layers that implement the things registered. + +As an example of this continuum, the complexity needed for building and distributing blocks or building and distributing themes should be minimal. As you get closer to working within Gutenberg internals directly, it does require more understanding of various technologies and technical stacks to be effective in this area. + +The other perspective is that of the **creator **of content using Gutenberg where the UI/UX should present very simple “keep out of my way” interactions until more complex requirements are needed which are “revealed” when and as needed. + +An example here would be creators discovering they can move a block into another block in various contexts and discovering it _just works_. So even learning basic interactions can help _empower_ more complex interactions through the delight of experimenting as a natural outflow of the creative process. A great example of this is the power of multi-block transforms. + +There’s also the related application here to design systems in larger organizations where the design team wants to put some restrictions on what can be modified and manipulated by the content creation team in keeping with the chosen designs behind the presentation of that content. In this case, the progressive complexity principle in Gutenberg provides the tools for “locking down” various elements of the editor when and as needed depending on who is working with the content. Entire swaths of the interface could be hidden or removed to account for the fluent needs of those interacting with the content. + + +## Ubiquitous and Safe Adoption + +This encompasses the idea of _backwards compatibility_ and _graceful degradation_. + +“One’s existing content should never be lost or generally affected by the switch to a new editor. The newer tool should understand the content natively or at the very least leave it undisturbed.” (Backwards compatibility principle in “[The Language of Gutenberg](https://lamda.blog/2018/04/22/the-language-of-gutenberg/)” - Miguel) + +This also encompasses the ideas of _portability and freedom from lock-in_: + +“One’s content shouldn’t be tied to anything. This means that content shouldn’t be tied to any runtime, be it Gutenberg or WordPress in general, and that a good relationship with other editors (mobile apps, MarsEdit, etc.) should be developed.” (Portability principle in “The Language of Gutenberg - Miguel) + +“Adopting Gutenberg for early testing or curiosity shouldn’t be an irreversible action for one’s content. Disabling Gutenberg shouldn’t result in unreasonably altered content. The same should later apply to third-party blocks. There is a strong desire to fight lock-in, which is not new but is pervasive in a world of proprietary software and software-as-a-service.” (No commitment principle in “The language of Gutenberg - Miguel) + +This also embraces the promise of the Web where content is replicable in multiple ways across devices and apps. It’s the idea that the basic block structure proves to be a timeless and reliable way of representing the content and meta information about that content. + +Imagine a world where content created by Gutenberg can be consumed and read _anywhere_. This is largely why at the heart of the block structure, the format is largely an enhancement on top of HTML. + +“Ultimately, choosing HTML means that — as with a painting or a sculpture — the editor’s final artefact is the canonical format of the content, not a byproduct thereof.” (The Language of Gutenberg - Miguel). + +This manifests in letting machines do what machines are good for, and preserve content in a format that is readable to users. + +Finally, the principle of ubiquitous and safe adoption is found in the way Gutenberg is being developed _incrementally_. WordPress powers ~ 40% of the Web and the changes that GB brings cannot happen overnight (Gutenberg or the ship of Theseus - Matías) + + +## Resources + +* [Gutenberg or the ship of Theseus](https://matiasventura.com/post/gutenberg-or-the-ship-of-theseus/) (Matías Ventura Bausero) +* [The Language of Gutenberg](https://lamda.blog/2018/04/22/the-language-of-gutenberg/) (Miguel Fonseca) +* [Embrace the Modularity](https://riad.blog/2020/01/28/embrace-the-modularity/) (Riad Benguella) +* [Gutenberg Posts Aren’t HTML](https://fluffyandflakey.blog/2017/09/04/gutenberg-posts-arent-html/) (Dennis Snell) +* [We called it Gutenberg for a Reason](https://ma.tt/2017/08/we-called-it-gutenberg-for-a-reason/) (Matt Mullenweg) From 1512b6798be50370ac28e75dfdd9cdedb6b135a9 Mon Sep 17 00:00:00 2001 From: Darren Ethier Date: Mon, 19 Apr 2021 10:22:40 -0400 Subject: [PATCH 02/13] fix typo with markdown emphasis --- docs/explanations/principles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/explanations/principles.md b/docs/explanations/principles.md index 754a57527451fc..dc746d6c4aa172 100644 --- a/docs/explanations/principles.md +++ b/docs/explanations/principles.md @@ -67,7 +67,7 @@ As it applies to **developers** (plugin or theme), progressive complexity means As an example of this continuum, the complexity needed for building and distributing blocks or building and distributing themes should be minimal. As you get closer to working within Gutenberg internals directly, it does require more understanding of various technologies and technical stacks to be effective in this area. -The other perspective is that of the **creator **of content using Gutenberg where the UI/UX should present very simple “keep out of my way” interactions until more complex requirements are needed which are “revealed” when and as needed. +The other perspective is that of the **creator** of content using Gutenberg where the UI/UX should present very simple “keep out of my way” interactions until more complex requirements are needed which are “revealed” when and as needed. An example here would be creators discovering they can move a block into another block in various contexts and discovering it _just works_. So even learning basic interactions can help _empower_ more complex interactions through the delight of experimenting as a natural outflow of the creative process. A great example of this is the power of multi-block transforms. From 0c8847fd8c21d1a62674fb836660280e1a9c3b0d Mon Sep 17 00:00:00 2001 From: Darren Ethier Date: Wed, 21 Apr 2021 07:45:20 -0400 Subject: [PATCH 03/13] Improve reference to WordPress usage stats. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Greg Ziółkowski --- docs/explanations/principles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/explanations/principles.md b/docs/explanations/principles.md index dc746d6c4aa172..6a82be0ebc4fc1 100644 --- a/docs/explanations/principles.md +++ b/docs/explanations/principles.md @@ -94,7 +94,7 @@ Imagine a world where content created by Gutenberg can be consumed and read _any This manifests in letting machines do what machines are good for, and preserve content in a format that is readable to users. -Finally, the principle of ubiquitous and safe adoption is found in the way Gutenberg is being developed _incrementally_. WordPress powers ~ 40% of the Web and the changes that GB brings cannot happen overnight (Gutenberg or the ship of Theseus - Matías) +Finally, the principle of ubiquitous and safe adoption is found in the way Gutenberg is being developed _incrementally_. WordPress powers over 40% of the Web and the changes that GB brings cannot happen overnight (Gutenberg or the ship of Theseus - Matías) ## Resources From d6db504b0b87806ec0ae4307560834e225f2c329 Mon Sep 17 00:00:00 2001 From: Darren Ethier Date: Tue, 18 May 2021 15:28:27 -0400 Subject: [PATCH 04/13] Simplify first principle and improve the description. This moves away from using the word delightful and incorporates some language used by Matias to describe interface principles (@see https://github.com/WordPress/gutenberg/issues/18667) --- docs/explanations/principles.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/docs/explanations/principles.md b/docs/explanations/principles.md index 6a82be0ebc4fc1..e4d8b6e812810f 100644 --- a/docs/explanations/principles.md +++ b/docs/explanations/principles.md @@ -9,23 +9,21 @@ An important thing to keep at top of mind when reviewing these principles is tha When applied, sometimes these principles build on each other much like the idea of constructing a house with a foundation, walls and roof. However, other times the application of the principles results in something that is more similar to a tapestry where threads of each principle are embedded together and evident in the finished feature or design of the project. -## Aim for delightful, consistent, accessible user interfaces for empowering content creation and expression. +## A canvas for expression. _“Optimize for the user” (Matias - [Gutenberg or the Ship of Theseus](https://matiasventura.com/post/gutenberg-or-the-ship-of-theseus/))_ -Each of the words in this principle are deliberate: +The block canvas is the primary interface and brings about the expectation of *direct* manipulation. Blocks can define multiple states, variations, and can mutate. The canvas of the block should: +### Guide users around interacting with the content. -### Delightful +For this, the interface needs to welcome exploration and to be able to teach its affordances intuitively. It should result in experiences producing "aha!" moments when users create their content (see [here for an example](https://twitter.com/colemank83/status/1371846826664591364)). -The user interfaces should “get out of the way” and support the user in creating their content. They should lead to experiences where the user (in the vernacular of Marie Kondo) _finds delight_ with each new thing they discover they can do or accomplish. +Interactive tools should be contextual when needed, and focus on supporting the user in creating their content - present when needed and getting out of the way when not. +### Uniformity within diversity -### Consistent - -Any interfaces are consistently applied. Users should be able to _rely on muscle memory and learned patterns_ as they become familiar with how it works. - -This also applies to learning _where to find_ different elements that the user might interact with in creating their content. +Learning the ingredients of the interface happens once, but scales to hundreds of blocks. Users should be able to *rely on muscle memory and learned patterns* as they become more familiar with the interface. ### Accessible From 5e8d288478aa2a5ff079e1129cb1fef3c54b0afc Mon Sep 17 00:00:00 2001 From: Darren Ethier Date: Tue, 18 May 2021 15:32:36 -0400 Subject: [PATCH 05/13] Edits to references and ensure all are linked. --- docs/explanations/principles.md | 21 +++++---------------- 1 file changed, 5 insertions(+), 16 deletions(-) diff --git a/docs/explanations/principles.md b/docs/explanations/principles.md index e4d8b6e812810f..f6d0ce12cdd653 100644 --- a/docs/explanations/principles.md +++ b/docs/explanations/principles.md @@ -1,5 +1,3 @@ - - # Gutenberg Principles This document has been written so that those contributing to the Gutenberg project can have some understanding of what guides decisions around what is included in the project (or not). @@ -11,13 +9,13 @@ When applied, sometimes these principles build on each other much like the idea ## A canvas for expression. -_“Optimize for the user” (Matias - [Gutenberg or the Ship of Theseus](https://matiasventura.com/post/gutenberg-or-the-ship-of-theseus/))_ +_“Optimize for the user” (Matías - [Gutenberg or the Ship of Theseus](https://matiasventura.com/post/gutenberg-or-the-ship-of-theseus/))_ The block canvas is the primary interface and brings about the expectation of *direct* manipulation. Blocks can define multiple states, variations, and can mutate. The canvas of the block should: ### Guide users around interacting with the content. -For this, the interface needs to welcome exploration and to be able to teach its affordances intuitively. It should result in experiences producing "aha!" moments when users create their content (see [here for an example](https://twitter.com/colemank83/status/1371846826664591364)). +For this, the interface needs to welcome exploration and to be able to teach its affordances intuitively. It should result in experiences producing empowering "aha!" moments when users interact with it (see [here for an example](https://twitter.com/colemank83/status/1371846826664591364)). Interactive tools should be contextual when needed, and focus on supporting the user in creating their content - present when needed and getting out of the way when not. @@ -25,21 +23,12 @@ Interactive tools should be contextual when needed, and focus on supporting the Learning the ingredients of the interface happens once, but scales to hundreds of blocks. Users should be able to *rely on muscle memory and learned patterns* as they become more familiar with the interface. - ### Accessible Being accessible is a holistic principle that embraces not only the desire that _everyone can work with Gutenberg interfaces no matter their ability_ but also that the improvements made are _equitable_ and improve the experience for _every_ user. This is a lofty challenge and definitely hard balance to get right - but already there is fruit being born in the improvements that have been made to the user interface over the last few years. Modern web application development brings its own set of accessibility problems around standards and consistent application between browsers which often requires some unique solutions that might not be apparent on the first attempt. So we acknowledge that accessibility is not something that can be implemented statically but instead is an ongoing part of the interface creation and refinement. - -### Empowering - -With delightful, consistent, and accessible interfaces we are aiming for empowering users to try and do things that they assumed were beyond their capabilities and reach before. We strive for those “Aha” moments of surprise and wonder as folks discover how they can unleash their creativity. - -Example: https://twitter.com/colemank83/status/1371846826664591364 - - ## Curated Extensibility The use of the word _curated_ expressly refers to implementing extensibility in a way that prioritizes those _using Gutenberg interfaces to create their content_ over developers integrating with the system. As a result, every extensibility interface request is filtered through the question of how it impacts creator workflows. @@ -57,7 +46,7 @@ Extensibility interfaces in Gutenberg favor: ## Progressive Complexity -_“On the Layers of the Onion”_ (Matias - Gutenberg or the Ship of Theseus) +_“On the Layers of the Onion”_ (Matías - [Gutenberg or the Ship of Theseus](https://matiasventura.com/post/gutenberg-or-the-ship-of-theseus/)) There are two perspectives for this principle: @@ -88,11 +77,11 @@ This also embraces the promise of the Web where content is replicable in multipl Imagine a world where content created by Gutenberg can be consumed and read _anywhere_. This is largely why at the heart of the block structure, the format is largely an enhancement on top of HTML. -“Ultimately, choosing HTML means that — as with a painting or a sculpture — the editor’s final artefact is the canonical format of the content, not a byproduct thereof.” (The Language of Gutenberg - Miguel). +“Ultimately, choosing HTML means that — as with a painting or a sculpture — the editor’s final artefact is the canonical format of the content, not a byproduct thereof.” (The Language of Gutenberg](https://lamda.blog/2018/04/22/the-language-of-gutenberg/) - Miguel). This manifests in letting machines do what machines are good for, and preserve content in a format that is readable to users. -Finally, the principle of ubiquitous and safe adoption is found in the way Gutenberg is being developed _incrementally_. WordPress powers over 40% of the Web and the changes that GB brings cannot happen overnight (Gutenberg or the ship of Theseus - Matías) +Finally, the principle of ubiquitous and safe adoption is found in the way Gutenberg is being developed _incrementally_. WordPress powers over 40% of the Web and the changes that GB brings cannot happen overnight (Matías - [Gutenberg or the Ship of Theseus](https://matiasventura.com/post/gutenberg-or-the-ship-of-theseus/)) ## Resources From 219f0af45e362be0e4880d67d961064301de1185 Mon Sep 17 00:00:00 2001 From: Darren Ethier Date: Wed, 19 May 2021 13:21:56 -0400 Subject: [PATCH 06/13] move link to principles doc into the top-level project README.md --- README.md | 3 +++ docs/README.md | 4 ---- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index aec379107a6fff..7af783033dbdd1 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,9 @@ The block editor first became available in December 2018, and we're still hard a Get hands on: check out the [block editor live demo](https://wordpress.org/gutenberg/) to play with a test instance of the editor. +### Gutenberg Principles +[The Gutenberg principles document](/docs/explanations/principles.md) highlights a few principles that are guiding the overall project and shape various development and design decisions. + ### Using Gutenberg - **Download:** To use the latest release of the Gutenberg plugin on your WordPress site: install from the plugins page in wp-admin, or [download from the WordPress.org plugins repository](https://wordpress.org/plugins/gutenberg/). diff --git a/docs/README.md b/docs/README.md index 8b482ee47c249a..fa253b6ea6f9a0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -19,10 +19,6 @@ The Editor offers rich new value to users with visual, drag-and-drop creation to [Learn to use the block editor](https://wordpress.org/support/article/wordpress-editor/) to create media-rich posts and pages. ## Quick links - -### Gutenberg Principles -[The Gutenberg principles document](/docs/explanations/principles.md) highlights a few principles that are guiding the overall project and shape various development and design decisions. - ### Create a Block Tutorial [Learn how to create your first block](/docs/getting-started/tutorials/create-block/README.md) for the WordPress block editor. From setting up your development environment, tools, and getting comfortable with the new development model, this tutorial covers all what you need to know to get started with the block editor. From 5e744d9161e752f95e206124264842798edc505b Mon Sep 17 00:00:00 2001 From: Darren Ethier Date: Wed, 19 May 2021 13:29:19 -0400 Subject: [PATCH 07/13] Add link to key architectural concepts (impacting extensibility) --- docs/explanations/principles.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/explanations/principles.md b/docs/explanations/principles.md index f6d0ce12cdd653..3ae356dfdb81cf 100644 --- a/docs/explanations/principles.md +++ b/docs/explanations/principles.md @@ -43,6 +43,8 @@ Extensibility interfaces in Gutenberg favor: **Experimentation** - Often new APIs and interfaces clearly start as experimental while reliability and usability of different approaches are being tested. These experiments always begin with determining what problem is solved from the _creator_ perspective and seek to validate how it impacts the user workflow. The intent is to explore what generalizations of the creator's use-case are possible and to discover better abstractions before solidifying around the contract exposed to extension developers. +For more information around currently built patterns for extensibility and key architectural concepts, see [this document](https://developer.wordpress.org/block-editor/explanations/architecture/key-concepts/)). + ## Progressive Complexity From 1a648ba43fce133010df1405b5f35a7c68349ad2 Mon Sep 17 00:00:00 2001 From: Darren Ethier Date: Wed, 19 May 2021 13:30:52 -0400 Subject: [PATCH 08/13] changed title of doc and tweak wording of relevant link in top-level readme --- README.md | 4 ++-- docs/explanations/principles.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 7af783033dbdd1..b6c45464f0239f 100644 --- a/README.md +++ b/README.md @@ -23,8 +23,8 @@ The block editor first became available in December 2018, and we're still hard a Get hands on: check out the [block editor live demo](https://wordpress.org/gutenberg/) to play with a test instance of the editor. -### Gutenberg Principles -[The Gutenberg principles document](/docs/explanations/principles.md) highlights a few principles that are guiding the overall project and shape various development and design decisions. +### Guiding Principles +[The Guiding principles document](/docs/explanations/principles.md) highlights a few principles that are shaping the overall project and impact various development and design decisions. ### Using Gutenberg diff --git a/docs/explanations/principles.md b/docs/explanations/principles.md index 3ae356dfdb81cf..291518a4d0b006 100644 --- a/docs/explanations/principles.md +++ b/docs/explanations/principles.md @@ -1,4 +1,4 @@ -# Gutenberg Principles +# Guiding Principles This document has been written so that those contributing to the Gutenberg project can have some understanding of what guides decisions around what is included in the project (or not). From f8a44afb3aa31d14972827a7801d4b734379a364 Mon Sep 17 00:00:00 2001 From: Darren Ethier Date: Wed, 19 May 2021 13:46:35 -0400 Subject: [PATCH 09/13] Improve wording around accessibility --- docs/explanations/principles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/explanations/principles.md b/docs/explanations/principles.md index 291518a4d0b006..a181abce691bba 100644 --- a/docs/explanations/principles.md +++ b/docs/explanations/principles.md @@ -25,7 +25,7 @@ Learning the ingredients of the interface happens once, but scales to hundreds o ### Accessible -Being accessible is a holistic principle that embraces not only the desire that _everyone can work with Gutenberg interfaces no matter their ability_ but also that the improvements made are _equitable_ and improve the experience for _every_ user. This is a lofty challenge and definitely hard balance to get right - but already there is fruit being born in the improvements that have been made to the user interface over the last few years. +Being accessible is a holistic principle that embraces not only the desire that _everyone can work with Gutenberg interfaces no matter their ability_ but also that the improvements made are _equitable_ and improve the experience for both those *creating* the content and those *consuming* the content. This is a lofty challenge and definitely hard balance to get right. As a canvas of expression, the project seeks to embrace the fact that users interacting with the software have distinct characteristics and preferences shaping helpful workflows for what they need to do. Modern web application development brings its own set of accessibility problems around standards and consistent application between browsers which often requires some unique solutions that might not be apparent on the first attempt. So we acknowledge that accessibility is not something that can be implemented statically but instead is an ongoing part of the interface creation and refinement. From e7b3960ea81c7eb83cd5052041e86f120da9a4b9 Mon Sep 17 00:00:00 2001 From: Darren Ethier Date: Wed, 19 May 2021 14:00:32 -0400 Subject: [PATCH 10/13] =?UTF-8?q?demphasize=20=E2=80=9Ccomplex=E2=80=9D=20?= =?UTF-8?q?in=20progressive=20complexity=20principle.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/explanations/principles.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/explanations/principles.md b/docs/explanations/principles.md index a181abce691bba..182acab76ef5f2 100644 --- a/docs/explanations/principles.md +++ b/docs/explanations/principles.md @@ -46,10 +46,12 @@ Extensibility interfaces in Gutenberg favor: For more information around currently built patterns for extensibility and key architectural concepts, see [this document](https://developer.wordpress.org/block-editor/explanations/architecture/key-concepts/)). -## Progressive Complexity +## Progressive Complexity unfolding from simple origins. _“On the Layers of the Onion”_ (Matías - [Gutenberg or the Ship of Theseus](https://matiasventura.com/post/gutenberg-or-the-ship-of-theseus/)) +The initial interfaces for those interacting with Gutenberg should be simple and straightforward yet provide a path through progressive complexity to accomplish what is needed for expressive content. + There are two perspectives for this principle: As it applies to **developers** (plugin or theme), progressive complexity means that there are degrees of ability and understanding needed in order to extend or contribute to Gutenberg. This has overlap with the _curated extensibility_ principle where some interfaces have clearly defined (opinionated) registration APIs that hide much of the complexity in the lower layers that implement the things registered. From f53db2899912f8bb2f6d80c3c78fc6570c861c1c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Greg=20Zi=C3=B3=C5=82kowski?= Date: Thu, 20 May 2021 07:57:41 +0200 Subject: [PATCH 11/13] Update docs/explanations/principles.md --- docs/explanations/principles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/explanations/principles.md b/docs/explanations/principles.md index 182acab76ef5f2..d45d668a935b30 100644 --- a/docs/explanations/principles.md +++ b/docs/explanations/principles.md @@ -43,7 +43,7 @@ Extensibility interfaces in Gutenberg favor: **Experimentation** - Often new APIs and interfaces clearly start as experimental while reliability and usability of different approaches are being tested. These experiments always begin with determining what problem is solved from the _creator_ perspective and seek to validate how it impacts the user workflow. The intent is to explore what generalizations of the creator's use-case are possible and to discover better abstractions before solidifying around the contract exposed to extension developers. -For more information around currently built patterns for extensibility and key architectural concepts, see [this document](https://developer.wordpress.org/block-editor/explanations/architecture/key-concepts/)). +For more information around currently built patterns for extensibility and key architectural concepts, see [this document](/docs/explanations/architecture/key-concepts.md)). ## Progressive Complexity unfolding from simple origins. From b8e217fe153ac3755f117ca98681395445a5a39c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Greg=20Zi=C3=B3=C5=82kowski?= Date: Thu, 20 May 2021 07:59:21 +0200 Subject: [PATCH 12/13] Update docs/explanations/principles.md --- docs/explanations/principles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/explanations/principles.md b/docs/explanations/principles.md index d45d668a935b30..ffd65eccd42ab6 100644 --- a/docs/explanations/principles.md +++ b/docs/explanations/principles.md @@ -43,7 +43,7 @@ Extensibility interfaces in Gutenberg favor: **Experimentation** - Often new APIs and interfaces clearly start as experimental while reliability and usability of different approaches are being tested. These experiments always begin with determining what problem is solved from the _creator_ perspective and seek to validate how it impacts the user workflow. The intent is to explore what generalizations of the creator's use-case are possible and to discover better abstractions before solidifying around the contract exposed to extension developers. -For more information around currently built patterns for extensibility and key architectural concepts, see [this document](/docs/explanations/architecture/key-concepts.md)). +For more information around currently built patterns for extensibility and key architectural concepts, see [this document](/docs/explanations/architecture/key-concepts.md). ## Progressive Complexity unfolding from simple origins. From 9b4eade1e287f766cf045b9f48b74bc7d13e84e1 Mon Sep 17 00:00:00 2001 From: Darren Ethier Date: Tue, 25 May 2021 05:31:07 -0400 Subject: [PATCH 13/13] Clarify usage of the word interfaces in the doc. --- docs/explanations/principles.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/explanations/principles.md b/docs/explanations/principles.md index ffd65eccd42ab6..a545f161b6e383 100644 --- a/docs/explanations/principles.md +++ b/docs/explanations/principles.md @@ -25,13 +25,13 @@ Learning the ingredients of the interface happens once, but scales to hundreds o ### Accessible -Being accessible is a holistic principle that embraces not only the desire that _everyone can work with Gutenberg interfaces no matter their ability_ but also that the improvements made are _equitable_ and improve the experience for both those *creating* the content and those *consuming* the content. This is a lofty challenge and definitely hard balance to get right. As a canvas of expression, the project seeks to embrace the fact that users interacting with the software have distinct characteristics and preferences shaping helpful workflows for what they need to do. +Being accessible is a holistic principle that embraces not only the desire that _everyone can work with Gutenberg user interfaces no matter their ability_ but also that the improvements made are _equitable_ and improve the experience for both those *creating* the content and those *consuming* the content. This is a lofty challenge and definitely hard balance to get right. As a canvas of expression, the project seeks to embrace the fact that users interacting with the software have distinct characteristics and preferences shaping helpful workflows for what they need to do. Modern web application development brings its own set of accessibility problems around standards and consistent application between browsers which often requires some unique solutions that might not be apparent on the first attempt. So we acknowledge that accessibility is not something that can be implemented statically but instead is an ongoing part of the interface creation and refinement. ## Curated Extensibility -The use of the word _curated_ expressly refers to implementing extensibility in a way that prioritizes those _using Gutenberg interfaces to create their content_ over developers integrating with the system. As a result, every extensibility interface request is filtered through the question of how it impacts creator workflows. +The use of the word _curated_ expressly refers to implementing extensibility in a way that prioritizes those _using Gutenberg user interfaces to create their content_ over developers integrating with the system. As a result, every extensibility interface request is filtered through the question of how it impacts creator workflows. Implementation details are ephemeral. Practically this means that the traditional WP approach of wrapping things in filters and liberal use of actions is avoided in favor of explicit extension interfaces that expose _functionality_ but hide the _implementation details._ Gutenberg has opinionated APIs that favor stability and functionality for the user over flexibility for the developer. @@ -50,11 +50,11 @@ For more information around currently built patterns for extensibility and key a _“On the Layers of the Onion”_ (Matías - [Gutenberg or the Ship of Theseus](https://matiasventura.com/post/gutenberg-or-the-ship-of-theseus/)) -The initial interfaces for those interacting with Gutenberg should be simple and straightforward yet provide a path through progressive complexity to accomplish what is needed for expressive content. +The initial user interfaces for those interacting with Gutenberg should be simple and straightforward yet provide a path through progressive complexity to accomplish what is needed for expressive content. There are two perspectives for this principle: -As it applies to **developers** (plugin or theme), progressive complexity means that there are degrees of ability and understanding needed in order to extend or contribute to Gutenberg. This has overlap with the _curated extensibility_ principle where some interfaces have clearly defined (opinionated) registration APIs that hide much of the complexity in the lower layers that implement the things registered. +As it applies to **developers** (plugin or theme), progressive complexity means that there are degrees of ability and understanding needed in order to extend or contribute to Gutenberg. This has overlap with the _curated extensibility_ principle where some extensibility interfaces have clearly defined (opinionated) registration APIs that hide much of the complexity in the lower layers that implement the things registered. As an example of this continuum, the complexity needed for building and distributing blocks or building and distributing themes should be minimal. As you get closer to working within Gutenberg internals directly, it does require more understanding of various technologies and technical stacks to be effective in this area.