Contributing to Gutenberg: A New Contributor’s Experience

The following is a guest post by Chris Van Patten who shares his experience learning and contributing to Gutenberg. There’s been a lot of talk of Gutenberg’s higher barrier to entry for new contributors. Van Patten is the founder of Tomodomo, a digital agency for magazine publishers.

Over the past few months, but especially over the last few weeks, there has been extensive conversation about the barriers to entry present in contributing to the upcoming Gutenberg editor for WordPress.

Of course, everyone’s experiences are subjective and unique. I can’t pretend to understand what everyone has felt. But my experience has been different than what some folks have been articulating, and I wanted to share my own take.

The Early Days

I’ve used WordPress for close to half my life; almost 15 years now. I remember some of the earliest versions of WordPress: the classic theme, the advent of Kubrick, MP6, up through today.

Early Days of the WordPress Backend

Like many in the community, I’m entirely self-taught. I have no background in computer science, and have no formal instruction under my belt. I picked up code through trial-and-error, tweaking files and breaking my site as I wanted to make changes.

Since those early days, WordPress was always my CMS of choice both for personal projects and for clients with my agency Tomodomo. But even though I had committed to the WordPress platform, my contributions back were limited.

The rules, rituals, and etiquette around posting on Trac seemed arcane and illegible. To this day, I could not make an SVN patch if my life depended on it. And much of the core code, imbued with years of history and backwards compatibility, was hard for me to pick apart.

So instead, I contributed in other ways: open sourcing simple custom plugins I was building, organizing WordCamps and meetups, and speaking at WordCamps around the globe. But it always bothered me that I couldn’t find a way to get those elusive ‘props’.

(Okay, so I did actually get props on one release, but I am convinced it was a mistake; I had neither opened the ticket or provided a patch.)

Going… Going… Gutenberg

When I first learned about Gutenberg and started exploring, I was apprehensive. At first it seemed scary. My JavaScript abilities didn’t extend beyond jQuery. React was inscrutable and it seemed like I’d need a doctorate to understand some of the ideas behind it. I still don’t understand how Webpack works its magic. Does anyone, really?

But the possibilities of the new block interface were too enticing to ignore, so I started diving in and figuring out how it worked. In those halcyon days (aka earlier this year), Gutenberg was still pretty rough around the edges, and there were a lot of opportunities for improvement. I started lurking on the GitHub repo, reading issues, examining the code, and generally trying to wrap my head around what the heck was going on.

As I was playing around with Gutenberg for a client project, I started reporting issues: simple things, like user interface bugs. I started commenting on tickets, usually offering suggestions for a particular feature, trying to advocate from the perspective of independent developers.

I even filed my first pull request! It was simple. I updated the README to include the day and time of the weekly #core-editor meeting (Wednesdays at 1pm UTC, if you’re wondering). It was an inauspicious beginning, but I was excited to get it merged.

Over time, my knowledge grew. It was like my early days in web development, learning a CSS property here, and an HTML element there. I learned what a component was and how you could reuse them in different situations. I learned about JSX, and ES6, and some of the other crazy acronyms you encounter in Gutenland.

As I was building more with Gutenberg, I was also finding new ways to build Gutenberg itself. I was able to understand more of the discussions, and offer my thoughts and suggestions. I started opening pull requests, largely dealing with design issues but also solving small bugs and quirks. I made a point of attending the weekly meeting I had previously added to the README, chiming in when I felt I had more perspective to share.

Today I have 25 new issues and 27 pull requests under my belt, in addition to dozens of comments on existing tickets. I’m a ‘member’ of the Gutenberg team on GitHub, and try to find time every day to triage new bugs or review pull requests. It took me most of the year to get to that point and it certainly wasn’t always easy. I still have so much to learn.

When I hear about how difficult it is to contribute to Gutenberg, I can’t reconcile that with my own experience. That’s not to say it’s a breeze: Gutenberg does things very differently than WordPress core, and there is undoubtedly a learning curve.

Advice for Contributing to Gutenberg

If you aren’t comfortable coding from day one, there are so many other ways to contribute. Read through issues and add your own ideas and suggestions. Try testing and replicating bug reports. Hunt through inline documentation for typos and grammar corrections. All of these are valuable, and always appreciated.

As you absorb the Guten-way through osmosis, you’ll find that the code isn’t as hard as you think — it’s just different. The intelligent people who build Gutenberg have done a great job at hiding away the ‘computer-science’ bits so the rest of us don’t have to worry about data binding and other complex ideas. I still cannot explain state management, data stores, or context APIs but I have managed to find small areas of the code to improve.

This isn’t to deny anyone’s frustration or confusion with Gutenberg and its development. Documentation is still lacking in many places. Some of the APIs are unintuitive. The tooling isn’t the simplest to set up. These are real problems, and I don’t want to pretend they don’t exist; we can undoubtedly do more to make Gutenberg development easier.

And of course I have privilege to check: I’m lucky to have the time to spend in the GitHub repo, experimenting with code, and participating in weekly meetings. I recognize that’s not a reality for many people.

If you can’t find the time, the Classic Editor will continue to be an option, and there’s no shame in prolonging the upgrade. It may take time for the Gutenberg experience to be as intuitive as we would all like it to be, and waiting for that is totally reasonable.

But if you open yourself to some new ideas about what WordPress can be, and can make the time, you may end up surprised at how easy it is to contribute. If you get stumped, pop into #core-editor or the forums. Don’t be afraid to post a bug report or suggestion; we might consolidate it with another issue if it was previously reported, but the additional information is still valuable. Every experience matters.

I’m incredibly excited about the future of WordPress with Gutenberg and to finally be a real WordPress contributor. We have a long way to go, but that means there are still many exciting ways to make a difference. The project will only get stronger with more independent community voices chiming in.

I hope you’ll join us!


17 responses to “Contributing to Gutenberg: A New Contributor’s Experience”

    • This all went completely over my head. I am just a simple blogger who chose WordPress six years ago because it was the easiest and most intuitive platform for someone new to blogging.
      But I am 66 years old, and find adapting to technical changes all but impossible. So for me, the changes to posting and editing might be the last straw for a non–tecchy blogger, still using a PC tower system.
      I hope that WP will introduce some very simple tutorials for the likes of me, and everyone who is in the same boat.
      Regards, Pete.

      • Hi Pete,

        There are some pretty good tutorials out there already, such as this one I found while searching ‘beginner Gutenberg tutorials’ –

        You can actually play with the most recent version of Gutenberg at –

        Now keep in mind, there may be a slight learning curve to get used to the new editor, and there will be minor adjustments before it’s pushed to core.

        That being said, I found it pretty intuitive and useful in a lot of ways after about ten to fifteen minutes of playing around with it. Your milage may vary!

      • Hi Pete! You’re definitely not alone. This post is written from the standpoint of a developer, not so much for a blogger that doesn’t touch the code on their site.

        Gutenberg IS a major change to the editing interface, but for your use, I’m guessing the biggest barrier is just going to be finding where the settings have moved around and learning about the new capabilities you’ll have.

        Our team wrote a free Guide to Gutenberg ebook you might find helpful. If nothing else, takea few minutes to skim chapters one & two – those give a very clear overview of what the block editor is and how it differs from the classic editor.

        The rest of the book digs into more detail on preparing your site and actually making the shift. We included instructions on how to NOT use Gutenberg, too :)

        Hope this helps alleviate some of your fears!

  1. Thanks for sharing your story, Chris.

    Your story with Gutenberg resembles mine with Core and PHP twelve years ago. Read issues, comments, code, go for the simple first. Not just to contribute, but to educate one selves on the possibilities of WordPress and how to change how it behaves, add something new that you or clients need to be productive.

    Few knows how every corner of WordPress works, and few will know how every corner of Gutenberg works. Few need to. What we need is, for core, the Plugin and Theme APIs, and similar for Gutenberg. It’s still/also a framework for making change and add new things.

    However useful, shortcodes are a nightmare. Having a visual editor and still have to rely on shortcodes, especially nested ones. Like editing html for people who hasn’t a clue about it. They easily destroy them, or the structure, trying to edit them or make mistakes trying to avoid editing them. Or remove them all, start from scratch with tools like Ultimate Shortcodes plugin.

    Take Jetpack contact form as example. It started as a simple shortcode, no alternatives. Then evolved into a nested shortcode, each field an inner shortcode. Then a popup edit panel to insert or edit it. Finally as a kind of block inside the visual editor, with in-block editing and a save button, like how the page builders work. But it you forgot to save the “block” changes before updating the post, the changes was gone (still is like that). And the form, even in visual doesn’t quite look like the resulting form when appearing on the front.

    I have made shortcodes and visual editor buttons to make things like custom style boxes, like for facts. They have background color among other things. When authors want the same box in another post, whatwas the color? Added some default colors, but thenthey want another and some other styling for a new purpose. Endless. Make my own system to to save such layouts and pick them up? Could be done.

    I took one of my shortcodes, a very, very simple one, displaying some info, and converted into a Guteberg block, while still working as a shortcode. Saw an example and did it in 30 minutes. No React, no Javascript. The is an API for server rendered blocks, available in PHP.

    All the above will be blocks, separating them from other blocks so they can be edited without mixing up or breaking things, by anyone. New sets of attributes, visually rendered on the fly, can be saved for later use, and have a name.

    Many have inline ads. Where to put them and how will they look? Offending in this context? Then move. Some even have trouble moving, by cut and paste, shortcodes without screwing up.

    Making highly dynamic blocks, like table of contents, list of other blocks by type, things that react to the local editing context or environment, will have to be made in Javascript and/or React, I suppose. Not there yet, for me, but how exciting to be able to, just by learning some more. Since I havn’t tried yet, I’m sure I will master it.

    Blocks are he answer to so many things. Blocks are not specific to bloggers, but for all article or rich text writers and editors.

    Gutenberg is complex behind the scenes, so is WordPress. Making complex layouts has never been easy in WordPress, not when changing theme or relying on plugins that do their task in very different ways, locking you in.

    WordPress has become quite archaic in many ways, compared to other tools. Gutenberg is thinking new, out of the traditional editing experience. WordPress is about to become greater than ever.

    • Saw an example and did it in 30 minutes. No React, no Javascript. The is an API for server rendered blocks, available in PHP.

      Would you mind sharing this? While I love Gutenberg, React thing and the setup procedures slow me down. If there’s a way to avoid this, it’s a big time saver.

  2. Hey Chris,
    thanks for you post. I’ve almost had the same experience as you. I startet using WordPress more than 12 years ago. With working on websites I learned CSS, HTML and PHP. My JavaScript knowledge was more copy&pasting code from Stackoverflow or writing some small jQuery scripts. My contribution in code to WordPress Core was really small, just a few small code corrections.

    I see Gutenberg as a chance to dive deeper into JavaScript. Since one year I am working more intensively with Gutenberg. Thanks to the Gutenberg team I have learned a lot during this time. I also started with reading the issues and trying to understand the PRs. Then at some point I opened my first ticket and finally the first pull request.
    You get feedback very quickly and can expand your knowledge and improve the code even further. Today I regularly create pull requests, triage and test issues, or review code from other contributors.

    I’ve invested a lot of time, but it’s worth it. I also haven’t understood all the concepts 100% yet, but I have been able contribute a lot to the project and the future of WordPress. Step by step the project Gutenberg and the code makes more and more sense and I understand the concepts behind it. By giving something back to the project, your skills and understanding of JavaScript grow.

    Any help is very welcome, even if it is a very small idea or change. Start small and grow ;-)

  3. While I don’t have a lot of time myself to contribute right now, as I’m running my small business and maybe switching to full time employment, I did catch the first issue with how to deal with permalinks many months ago and that set off a chain of discussion on how to resolve the fact that there was early way to edit a permalink. I reported the issue and it’s gone on its merry way to some form of resolution.

  4. I hate to bust all out here to whine on your blog, but I’m not looking forward to this Gutenberg editor at all. I’m not at all impressed with the way it transforms everything into a block. For example, when I write a blog post, normally I write it in Notepad… yes the old basic Notepad. In Notepad I write all my content with paragraphs, including header text, bold text where needed, plus any other content I needed (all edited with the proper html codes. Then I copy/paste what I’ve written into this Gutenburg blog wrecker and what happens… every line where there is a seperation in the content I’ve written is turned into a seperate block… why? That’s dumb. I don’t need every paragraph turned into a seperate block. It really makes the whole editing experience confusing. I don’t need a seperate block to set a header between paragraphs. I don’t want a seperate block just to add a photo somewhere in there.

    I’m in the middle of building a new business site and this Gutenberg editor is doing nothing but causing me headaches, and I’m slightly starting to hate bothering with WordPress since I turned Gutenburg on when the option came up. I don’t have time to learn someone’s supposedly best new way to write a blog post.

    • Picked up this to comment, because you mention Notepad. I sometimes use a similar text editor to clean up formatted text copied from other sources, like a PDF, and I, of course, expect I can easily paste the result in.

      Pasting text from a plain text editor, like Notepad or any, should just work in both classic (text or visual) and Gutenberg. Checked this with Gutenberg and it works perfect. It creates one block per paragraph as when typing directly.

      In the sense of text, a block just equals a paragraph. Forget the blocks and the number of them until you need to adjust, rearrange, reformat or change into quote, for example. In text context a block is just the piece of the text that you may want to do something with as a whole.

      Visual editor also have “blocks”, just not called that. When you want to edit and/or reposition an image, you do that as a block.

      When you want to change the level of a heading in classic visual, you need to mark that line(s), making it a kind of “block” for a while. But you have to tell the editor how to treat it as a block, marking the edges of it, before being able to change it, just it and not some extra characters. When it’s already a block such is easier and feels more natural.

      • Thanks for responding.

        I didn’t even think my comment would go up since I was ranting lol.

        Anyway I get what you’re saying (I think – pretty much). My main problem is that the majority of my work doesn’t need a seperate block for every line of text I write.

        For example, if I we’re to copy/paste these comments into Gutenburg, it would create a block where every line break occurs. That to me is chaotic and unnecessary. Is there a way to copy/paste text all into one block?

  5. I wish all those ‘experts’ would stop bullying people into their fancy experiments.
    I have had a devil of a job trying to get back to the easily understood and workable WP I enjoyed using, and the grotty Gutenberg is a lousy replacement.
    We had the same intimidation from Classic Yahoo into their inferior new version and while I’m sure internet aesthetes delight in such experimentation, it should be voluntary.,

  6. Hi, I’m awaiting to see how blind-friendly the new editor’s version will be. I found a plug-in to disable it in the meantime. I don’t know why they change the editor, as it took away the accessibility features.


Subscribe Via Email

Enter your email address to subscribe to this blog and receive notifications of new posts by email.