1. WPezDeveloper

    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. Miroslav Glavić

    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.


    • Jonathan Bossenger

      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.


    • Milana Cap

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

      There are even guidelines for writing technical documentation in accordance with WordPress community values. https://make.wordpress.org/docs/handbook/documentation-team-handbook/tone-and-voice-guide/


      • mfs

        “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)?


        • Milana Cap

          “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. Kranjcar

    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. William Patton

    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. Rod Olman

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


  6. Bastian

    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. Anne McCarthy

    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 🙂


    • Jonathan Bossenger

      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.


Comments are closed.

%d bloggers like this: