WordPress Contributors Seek Sponsorship for Improving Gutenberg Developer Docs

WordPress developers Milana Cap and Jonathan Bossenger are starting a fundraiser for improving Gutenberg developer documentation. The conversation began yesterday when Cap tweeted about how documentation is often overlooked when companies hire full-time contributors to work on WordPress.

“When your community is unable to learn your software then you have no contributors,” Cap said. “Documentation and tutorials are far more important for Open Source Software projects than people realize.”

The first time Cap began asking for Gutenberg documentation was at the Community Summit in Paris, 2017. She has been trying to direct the community’s attention to it since then.

“There are many holes in block editor documentation for developers but the most obvious one is how to start,” Cap said. “The beginning of documentation for developers doesn’t say anything about getting started. “It says only what you can do with a block but not _how_. Junior developers, PHP-only developers and anyone for whom is that documentation meant, doesn’t know how a block’s code looks, where to put it, how to include it, etc, let alone how to build a custom block with custom components and settings.”

Part of the challenge of documenting the block editor is that it is under active development. Enhancements and refinements are constantly pushed out to the Gutenberg plugin and keeping track of what is or is not currently available in core is not always easy. As WordPress is imminently introducing block directory search, it is a good time to formalize block creation documentation.

“Code examples are alarmingly missing all over docs,” Cap said. “The most basic examples exist but how to actually build something usable is missing. So, on this first page we are sent to a tutorial but that tutorial is not optimized for people who have never built a block before. Following it, I have and will fail to build the block.”

Marcus Kazmierczak and a team of documentation contributors are attempting to rebuild the tutorial in the official block editor handbook. A GitHub issue focused on addressing gaps in the current developer documentation is home to an active discussion about the best way to rewrite the docs for people who are new to block development.

“This is a very good start but there’s still a lot of work to be done,” Cap said. “Complete documentation is written by people who know and understand React and Gutenberg but are ‘cursed with knowledge.’ They don’t have much time to spend on understanding just how much others don’t know and in what detail documentation should be written. To be honest, I don’t think they should spend their time on that. We have a Documentation Team and we are willing to jump in but some sort of bridge is necessary.”

The Problem with Gutenberg Developer Documentation: It’s Not Friendly for Newcomers

“The ‘problem’ as I see it with the block editor documentation is that, unlike other WordPress documentation, it is written for experienced JavaScript developers, and not aimed at beginners,” Bossenger said. “I should also point out, this is by no means a shot at the folks who have put the current documentation together, and I appreciate any and all work they have done so far, it’s just in serious need of a review and some refinement.”

Bossenger said in the past WordPress made it very easy for anyone with a limited amount of PHP knowledge to quickly build a plugin or theme using action and filter hooks. It was easy to look at the code and understand what it was supposed to do.

“Modern JavaScript, and specifically React, is a very different kettle of fish,” Bossenger said. “It requires a deeper level of knowledge of how React works, including new terminology and practices. Modern JavaScript can also be very confusing, especially if this is the first time you’re seeing things like arrow functions, or less verbose if statements.

“If the closest you have come to working with JavaScript in WordPress has been using jQuery, switching to React based Gutenberg development still requires some learning on your part.”

After taking two courses before he could build anything for the editor, one on React and one on Gutenberg, Bossenger said the current Block Editor handbook is not written for developers with no experience in React and modern JavaScript. He believes it needs a restructuring to better explain new concepts and fit a pattern that is easier for a newcomer to consume. He highlighted the Plugin Developer handbook as an example where the chapters follow a structure and use terminology that is more like a text book, slowly introducing the reader to new concepts.

“I would argue that it would be quite possible for someone with no plugin or PHP knowledge, armed with this handbook and Google, to build a simple plugin to meet their specific requirements quite quickly,” Bossenger said. “Currently the block editor handbook is not conducive to this.”

Bossenger is not alone in his opinion of the current documentation. Peter Tasker at Delicious Brains recently published a tutorial on creating a custom Gutenberg block. Even after working with React full-time for the past year, he found the official block editor docs to be “kind of all over the place” and difficult to parse.

After Cap commented about the lack of companies sponsoring full-time work on documentation, Bossenger tested the waters with a tweet asking if the two of them might be able to raise funds for improving Gutenberg docs.

“Just the same as Block Editor Team (and any other Make team), the Documentation Team is understaffed,” Cap said. “We can’t afford to dedicate few members to first learn and then write documentation on developing with block editor. This is the main reason for my tweet. You’ll see sponsored contributors all over core but not in documentation and I’ll dare to say that both are equally important.”

Before launching their fundraiser, Cap and Bossenger plan to go through the existing documentation, pinpoint obvious holes, and identify questions that remain unanswered for those who are new to developing for the block editor.

“Once we have a plan we can predict how much time is needed for each part,” she said. “With this plan, we will go in search for sponsors. I think there will be an option to donate even before that but nothing is certain at this point.”

Blocks are the new frontier of WordPress development. Investing in solid documentation and tutorials for beginners could have a major impact on expanding the block ecosystem. This also indirectly benefits users as they end up with a more diverse directory of blocks to choose from when customizing their WordPress sites.

Bossenger and Cap are currently working on a plan for the docs ahead of announcing their fundraiser. In the meantime, anyone who wants to contribute to improving the block creation documentation can jump in on the GitHub discussion.


14 responses to “WordPress Contributors Seek Sponsorship for Improving Gutenberg Developer Docs”

  1. You can add this to the list of things found under: “Gutenberg – A Case Study on How Not to Launch a New Product”.

    The truth is, there’s no incentive for the “rich & powerful” to enable to WP masses. As long as the knowledge is controlled by the few, the many will struggle to cross the moat, if they bother at all. Less competition for the R & P. Sound familiar?

    It’s 2020. The Exerience is The Product. That is, the full end-to-end experience; docs included. In that context, Gutenberg’s struggles are no surprise.

  2. The problem for me to sponsor someone is that, morally I couldn’t, as someone who’s mother tongue is not English…Would the docs be only in English? My two mother tongues are Croatian and Spanish.

    Milana is from Serbia (from her twitter bio and her website’s about me page)…Croatian and Serbian are similar but different alphabets. Croatian uses Latin Alphabet, Serbian uses the Serbian Cyrillic Alphabet.

    I haven’t tried to use Cyrillic in 25 years. (At one point Croatia and Serbia were part of the same country).

    What about other languages that use Latin, Cyrillic or another Alphabet?

    What about the different dialects? As a Canadian, our English is a mix of American and British English (however closer to British English). Some words are different. Americans would call it a sweater, British call it a jumper. Americans call the front of the car HOOD, British call it the BONNET.

    In Spanish, my Spanish comes from Peru. Peruvian Spanish has differences to Venezuelan Spanish, Mexican Spanish, Argentinian Spanish and even Spain Spanish.

    I am sure other languages will go through it.

    WordPress is a global product, I wish the documentation could be done in as many languages as possible.

    I have sponsored people in the WordPress community in the past but this would be something I can’t morally.

    Let’s say I sponsor Milana, obvious languages would be English and Serbian. What about other languages? I couldn’t even sponsor one person per language. In the example with Milana, she could do two languages for the documents and maybe more if she knows other languages. I know there isn’t a single person that speaks a tonne of languages.

    • Miroslav, you raise an excellent point.

      While I can’t speak for Milana, I do know that there is a large WordPress community in Europe, who is just as passionate (perhaps even more so) about the growth and stability of WordPress.

      Personally, I see our sponsorship efforts as a two fold process
      a) allow existing contributors the time to get the current documentation up to a level that is easy to follow and understand.
      b) once that is complete, allow for other contributors from around the world to translate that documentation into different languages.

      The recent trend toward sponsoring open source projects, and the open discussion around that trend, shows that there are people who understand and value each others time, and are prepared to put some money towards achieving a common goal.

      So while you might not be prepared to sponsor our specific efforts right now, I encourage you to follow the project, and when the time comes for global translation efforts, to instead sponsor someone who can translate the documentation into Croatian.

      • “The language has no role in here. We are talking about official WordPress documentation, which is always written in English.”

        That’s the way we’ve always done it? That’s not a valid reason. Is the goal is to increase engagement with “the product”? Or maintain the status quo (which obviously isn’t working)?

        • “That’s the way we’ve always done it? That’s not a valid reason.”

          Not a valid reason for what?

          English is the language used throughout WordPress.org. There are Rosetta sites which are localised versions of WordPress.org. That’s where you get languages other than English. Rosettas are welcomed to include their own content, related to their local communities but some general content, such as About, Code of Conduct, Documentation etc is translated from WordPress.org, which is in English.

          I don’t understand the non working status quo regarding the choice of the language here.

  3. I understand you both, but I disagree.

    Instead of pointing out all that is not good, we should point to the solution on how to fix it.

    As for the “morality” of sponsoring the documentation, you Miroslave, couldn’t be more wrong.
    English documentation is the first step, and if done properly,everything else will be ok.

  4. I am ready to contribute what I can to this in both money and time. I benefit directly from improvements made here and welcome them.

    I too have struggled to get things working in a timely manner and relying on Google and 3rd party tutorials has been time consuming and frustrating to piece togwther all the relevant bits for my tasks.

  5. What is the official stance of Automattic on this? Surely that documentation is on the GB roadmap already?

  6. The official documentation is severly lacking. Right now, I merely use it for specific API details. As Milana says, the documentation is hostile to those of us coming from a PHP background. Also, the examples shown there are pretty basic and mostly useless for real-world development. Thanks to asking in StackOverflow and following tutorials in some developer blogs I managed to begin to grasp how to navigate this new environment. Also, most of the official documentation is centered in building blocks. If you need to adapt an old plugin that registers a custom post type and some meta boxes to the new Gutenberg UI, you are out of luck finding any decent tutorial there.

  7. Thanks so much for writing up this article and including the GitHub issue I authored a few months ago. When I saw the title, I was hoping it would be mentioned as I’ve been keen to create some momentum behind this very necessary work. In talking with a variety of folks about Gutenberg documentation and, in my own experience, I’ve found too that there’s a gap when it comes to documentation. It seems to be born out of the tension between Gutenberg developers having institutional knowledge and folks who could work on documentation feeling like they don’t have the perceived expertise to help. To build on this conversation and topic, I wanted to share a few ways people can still get involved even if you don’t know dear Gutenberg inside and out. There are likely more ways so just see this as a starting point: 

    Create issues with specific questions that you are trying to do that is not documented.
    Review documentation/go through the tutorials to share what can be improved and what’s missing in the form of new issues. 
    Start writing documentation in Github/Gutenberg repo and ask others to fill in details. Gutenberg developers aren’t necessarily documentation experts so anything that can be done to wed the two would be amazing.
    Help with organizing the logistics of documentation. 

    This last option is what I did and a big way I like to help when I don’t have expertise! I also opened an issue just today about updating the FAQ for Gutenberg after noticing it was out of date while responding to a different issue: https://github.com/WordPress/gutenberg/issues/23763 I’m not a Gutenberg developer but still want to help move things forward and am really excited to see the work people like Marcus have done here around building out better resources for block tutorials. Hopefully, the above examples can help bridge that gap too for people to feel more empowered to help out with docs. 

    I’d love to hear from others about what can be done to make this easier as well. I’m @annezazu on WordPress.org slack and always welcome pings 🙂

    • Anne, please accept my apologies for not mentioning you in my part of the interview, your work has been extremely important to getting the momentum going behind updating the documentation for the Block Editor.

      Unfortunately when I originally retweeted Milana’s tweet, I didn’t expect it to get picked up by the Tavern so quickly, and gave a hasty answer in my response when they reached out to me.


Subscribe Via Email

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

%d bloggers like this: