Proposal: Document defining Gutenberg Principles #30963
Conversation
nerrad
changed the title
|
Size Change: +536 B (0%) Total Size: 1.62 MB
ℹ️ View Unchanged
|
gziolo
added
the
[Type] Project Management
docs/explanations/principles.md
Outdated
| Each of the words in this principle are deliberate: | ||
|
|
||
|
|
||
| ### Delightful |
There was a problem hiding this comment.
As much as I love this word, it's just not a good principle because it is so subjective. It has also been confiscated by commercial projects.
There was a problem hiding this comment.
Is it primarily the specific word you object to or also the meaning behind the choice of the word (and the intent of the principle)? If just the word itself, do you have any suggestions about what could be used instead?
There was a problem hiding this comment.
Delightful does sound a bit like marketing-speak. It's not so much the subjectivity as the underlying idea that we're somehow directing the user's feelings about the product that makes me uneasy.
The word "transparent" popped into my head when reading The user interfaces should “get out of the way” and support the user. Transparency both in the sense of clarity (it's clear how to use the interface, thus "supporting" the user instead of making things difficult) but also in the sense of invisibility (it gets "out of the way" so users don't even notice it while working).
There was a problem hiding this comment.
You both have shared perspectives on the word "delightful" that I didn't even think of. I was thinking of it in the context of aiming for user experiences that elicit "surprised joy" (my interpretation of "delight"). I also don't think we can escape the reality that we indeed do influence users feelings about the product when building it. This principle is aimed at thinking how what we build contributes to positive feelings.
With that said, I do see how transparent could be a good substitute here for the word delightful and moves more towards the objectiveness of a principle as opposed to the subjectivity of a value or goal.
There was a problem hiding this comment.
"Delightful" doesn't capture what I think this section hints at. "Transparent" is also lacking a bit in concrete meaning.
The way I'd describe this is "A canvas for expression" (more on that here: #18667)
There was a problem hiding this comment.
I'll see if I can capture some of what you wrote in that issue Matías - ❤️ it.
There was a problem hiding this comment.
See the changes made in d6db504. I incorporated much of what Matías articulated in #18667 and this forms the basis for the revised content of the principle which is now simply "A canvas for expression" with the supporting points of this canvas:
- Guiding users around interacting with the content
- Uniformity within diversity
- and Accessbility
The wording around accessibility has also been tweaked in f8a44af which includes not only the work around this for creators of content, but also for consumers of content (to address what was brought up here).
This also handles the concerns around the word "delightful".
|
This is a great document. I don't have much to add to be honest :) |
There was a problem hiding this comment.
This is a great document. @nerrad, you did an extraordinary job to put it all together in such a thoughtful way.
I left some minor thing like missing links that I could spot when browsing:
It would be great to have a few more ✅ to ensure we all share the same principles 😄
docs/README.md
Outdated
| ### 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. | ||
|
|
There was a problem hiding this comment.
Can we move this section into the Contribute to the block editor below, I don't think it should be the first Quick Link.
This is the first page that shows when viewing the Block Editor Handbook and people are going to be more interested in how to build for and extend first.
With that also said, I think a better more prominent spot would be the repository top-level readme, as that is only showed within the repo and more likely target to developers of the project.
There was a problem hiding this comment.
I'm going to go ahead and move this into the repo top-level README.md - I agree it makes more sense to target contributors.
Given your comment here however, do you think I still need to expose this on on the built docs and if so, where do you think it should be in the docs structure?
There was a problem hiding this comment.
See 219f0af (and 1a648ba where wording was changed a bit).
|
I'd like to give this a bit more thought before merging. |
|
|
||
| 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/)”). |
There was a problem hiding this comment.
There's some overlap here with https://developer.wordpress.org/block-editor/explanations/architecture/key-concepts/ — it should be linked at least
docs/explanations/principles.md
Outdated
| @@ -0,0 +1,106 @@ | |||
|
|
|||
|
|
|||
| # Gutenberg Principles | |||
There was a problem hiding this comment.
I think "Guiding Principles" would be better.
docs/explanations/principles.md
Outdated
| 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. |
There was a problem hiding this comment.
I adhere to "empowering content creation and expression" but I'm not sure the other concepts capture the right concepts. 🤔
There was a problem hiding this comment.
What about something like:
The user experience is a canvas that empowers content creation and expression through intuitive and exploration friendly interfaces
docs/explanations/principles.md
Outdated
| 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 |
There was a problem hiding this comment.
This is not a principle I'd be comfortable stating as a primary guiding force because it's a bit more nuanced. The way I tend to describe this is more along the lines of "Providing uniformity within diversity, as learning the ingredients of the interface happens once but scales to hundreds of blocks."
This is an important design tension.
There was a problem hiding this comment.
I like the concept of "providing uniformity within diversity" but I think there's still the importance here of capturing the idea of not just the block interfaces but also the interfaces within the editor? Would you say this statement is a principle that also applies to the editor interfaces?
Also, is this something that you believe should be explicitly called out as it's own principle, or should it be included somehow as a part of the statement commented on here?
| This also applies to learning _where to find_ different elements that the user might interact with in creating their content. | ||
|
|
||
|
|
||
| ### Accessible |
There was a problem hiding this comment.
This one feels a bit odd as it's more of a general principle of WordPress at wide and not specific to Gutenberg. If anything, it should build upon the two other axis of "canvas for expression" and "uniform yet diverse" to embrace the fact users interacting with the software have distinct characteristics and preferences for how to use said software.
There was a problem hiding this comment.
There's also something important missing here which is how the software can help users build better websites that are semantic and more accessible. That is, respect for the viewers as well as the creators.
There was a problem hiding this comment.
That is, respect for the viewers as well as the creators.
This is definitely something that isn't capture well in the current iteration that should be included ❤️
This one feels a bit odd as it's more of a general principle of WordPress at wide and not specific to Gutenberg. If anything, it should build upon the two other axis of "canvas for expression" and "uniform yet diverse" to embrace the fact users interacting with the software have distinct characteristics and preferences for how to use said software.
While I agree it's a general principle of WordPress, I also think it's important to call out the distinctive nature of accessibility in the context of Gutenberg. I like how you reflect on describing this as software accommodating users with "distinct characteristics and preferences for how to use said software". An example of this is reflected in the numerous entry points people have to insert a block. Is there some specific concern here around the use of the word "accessible" itself here?
docs/explanations/principles.md
Outdated
| **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 |
There was a problem hiding this comment.
This needs to be balanced a bit more with a general seek for "simplicity"
There was a problem hiding this comment.
Content wise in the description of the principle, or reflected in the principle statement itself?
There was a problem hiding this comment.
This one was a bit difficult for me to address. I think in general I understand your feedback to mean we want to avoid the idea of complexity as a starting point for the interactions. I've made a few changes in e7b3960 which I think helps, but it still feels like it could be better expressed.
| 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 |
There was a problem hiding this comment.
I this is more about a profound respect for the user in an expansive sense — both in how it respects where they come from (compatibility) and aims to ensure protections for the future (the way user data is treated, for example)
There was a problem hiding this comment.
So is this more a comment on the principle wording itself (that you would like changed) or on the description of the principle?
There was a problem hiding this comment.
I left this as is, it's not clear to me how to improve it.
nerrad
force-pushed
the
add/gb-principles-doc
branch
from
e651743 to
8f65c69
Compare
Co-authored-by: Greg Ziółkowski <grzegorz@gziolo.pl>
nerrad
force-pushed
the
add/gb-principles-doc
branch
from
8f65c69 to
e7b3960
Compare
|
Sorry for the delay in addressing all the feedback. I've gone through and made changes and commented in the related threads to help highlight what was changed as a result. I think this is ready for another round of examination as folks are able. |
docs/explanations/principles.md
Outdated
|
|
||
| ## 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. |
There was a problem hiding this comment.
I'm having a little bit of trouble parsing this paragraph.
In "using Gutenberg interfaces to create their content", does interfaces refer to UI/user interfaces, or interfaces as a whole, including APIs?
Assuming the prior, maybe "prioritizes those using Gutenberg user interfaces to create their content"?
There was a problem hiding this comment.
Good point. Fixed in 9b4eade (which also clarifies the usage of interfaces elsewhere in the doc).
|
Just checking in to see if there's any appetite for seeing this land from other @WordPress/gutenberg-core contributors. I let this sit for a bit given the efforts around getting WordPress 5.8 released. In particular, @mtias, I addressed some feedback you had and I'm not sure you've seen it, or if you have additional comments. I'm happy to discuss/iterate more if needed (or even close the PR if there's no consensus). |
|
Thanks for the nudge — I'm still not quite happy with some of the items and headings. |
Based on this, it's not clear to me what are the next steps. I've assumed don't merge. I also do not know which items and headings are still problematic or what needs done to make them better. |
|
Sorry, I mean that some of the items in the outline feel at different levels but is not quite clear why. I don't have a concrete suggestion just yet. Perhaps it's trying to cover too much at once. |
|
That's very unfortunate to see this PR closed with no additions to the Block Editor Handbook 😞 I was hoping we will finally have a good reference to use when discussing new extensibility points. |
|
Agreed. How about after 5.9 we look to break this PR down into smaller documentation updates to various sections of the Block Editor Handbook? That way it will be easier to review and merge incrementally. |
|
Sorry folks, I closed this mostly because I felt it was stalled and I really had no clear idea on what some next steps could be taken to get it to a mergable state. While I do still think it'd be really helpful to have some master doc outlining principles guiding the project, I got a sense (maybe incorrectly) that there's still not sufficient consensus behind publishing this :). That's not necessarily a bad thing, it just means there's more work to do before something like this PR can be published.
One thing I've noticed with the feedback that has come in, is that there are some principles already sprinkled through various issues and docs already. Maybe all that is needed is to capture those and pull them into an index of sorts. The main outcome I was hoping from this PR was to have a single reference to point folks to for all the reasons I outlined in the PR description. |
| 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. |
There was a problem hiding this comment.
Still not happy with this heading. Feels too wordy and abstract.
|
I personally don't mind this sitting open, we can come back to it, others can read it and add thoughts. Some time distance can also clarify what works and what doesn't. |
|
Now that 5.9.0 is merged, would work on this get resumed? |
I've been involved with the Gutenberg project for a few years in different contexts: contributing directly to the codebase, participating in conversations around various interfaces, consuming what others have written about the project, writing plugins and blocks extending Gutenberg, consulting with teams working on it, and teaching others various aspects of the project. While there are various approaches to Gutenberg that are indirectly "picked up" by those working on it extensively as a by product of being "in the trenches", I have found that there's no real authoritative source for describing the underlying principles guiding Gutenberg development and design.
This lack manifests itself with some difficulty when trying to:
While there are a number of posts spread through various blogs and sources that articulate pieces of “Gutenberg principles”, to date there really isn’t a cohesive document than serves as an “official” repository of this guiding knowledge.
Having official principles guiding Gutenberg development can help in the following ways:
I believe there is an underlying set of ideas and principles that are guiding Gutenberg development and design whether it's communicated officially or not.
Given the above, and my own understanding of the Gutenberg project from my participation, observation, and usage, I'm submitting a proposed document with what I think some of the principles are guiding GB development and design. Some additional considerations: