Gutenberg: Consider only Updating Documentation on Release

[salcode]

Currently, the Gutenberg Documentation Website is updated from master every 15 minutes. source

While I understand the motivation in keeping the documentation as up-to-date as possible, it can be confusing when the behavior of the latest release varies from master.

My Experience

Working with the latest release v2.7.0 and following the documentation on Introducing Attributes and Editable Fields - Attributes, I was attempting to use RichText.Content. Unfortunately, RichText.Content was introduced since the latest release and only exists in master.

Suggestion

Clearly, I'm biased based on my experience but in my opinion, it would be preferable to freeze the documentation on the Gutenberg Documentation Website between releases.

Thanks for your consideration and for all of the great work being poured into this new editing experience.

[danielbachhuber]

Thanks for the suggestion, @salcode!

Clearly, I'm biased based on my experience but in my opinion, it would be preferable to freeze the documentation on the Gutenberg Documentation Website between releases.

Can you propose a workflow that might make this possible?

[manake]

I encounter this problem too (for example with styling ColorPalette via newly introduced CSS classes instead of inline styles) but I would vote for sticking to updating the documentation every 15 minutes. You can always sync master.

What I would vote for though: make the documentation BETTER. It's so unclear how to use for example "innerBlocks" at this moment (https://github.com/WordPress/gutenberg/tree/master/blocks/inner-blocks). MORE CODE EXAMPLES and COMPREHENSIVE CODE EXAMPLES (pieces of code that I could copy and paste and assemble something in 5 minutes instead of 5 hours).

Maybe even an interactive tool inside documentation for quick code generation... (would not take long to code but would be highly useful and very time saving for many people).

I would also vote for this: make MORE LISTS (or TABLES or JSON) in the documentation and LESS LARGE BLOCKS OF TEXT that are hard to read, find again etc.

Too many documentation pages in WordPress are bad. Please don't ignore documentation.

[salcode]

@danielbachhuber

Can you propose a workflow that might make this possible?

My apologies for not having a deeper understanding of the automatic syncing of the documentation currently, but perhaps the sync could be modified to pull from the most recent release/tag instead of master.

Someone working on the latest version of the plugin from master would still have access to the latest documentation on that branch, while anyone running the latest release would have that documentation on the Gutenberg Documentation Website.

While this does have the potential to have the Gutenberg Documentation Website lag, with the current pace of releases every two week, in my eyes this is a reasonable trade-off.

@manake, thanks for your thoughts on this topic, even though you disagree with me 😀

I encounter this problem too (for example with styling ColorPalette via newly introduced CSS classes instead of inline styles) but I would vote for sticking to updating the documentation every 15 minutes. You can always sync master.

Regarding the rest of your comment, I appreciate your concerns about improving documentation (as a developer, I always want to see improved documentation). A couple of notes:

1. Generally improving documentation is a bit off-topic for this issue, Consider only Updating Documentation on Release. Keeping an issue focused on a single idea really helps keep a project organized. You might want to open a more tightly targeted issue (or issues), like "Improve innerBlock documentation" or "Add InnerBlock Example".

2. Documentation is a huge task and a great opportunity to get involved. Some of the documentation modifications and suggestions you have could make great Issues/Pull Requests.

Thanks 😀

[ajitbohra]

I love the laravel documentation and the way it makes it possible to switch between different versions.

https://laravel.com/docs/5.6

[danielbachhuber]

My apologies for not having a deeper understanding of the automatic syncing of the documentation currently, but perhaps the sync could be modified to pull from the most recent release/tag instead of master.

This seems reasonable. It would add one step to the release process though: switching the URL the importer is using.

Also, it's worth noting that I think this problem will be less prevalent as time goes on. We're fixing bugs more than we're introducing new APIs at this point.

cc @WordPress/gutenberg-core for opinions.

[pento]

This seems reasonable. It would add one step to the release process though: switching the URL the importer is using.

It's an extra step that the people who generally build the releases can't perform, as it requires commit and deploy access to wp.org.

I appreciate that this can occasionally cause situations such as the one @salcode described, but this seems to be very rare. As @danielbachhuber noted, this will become even more rare over time, as the last of the APIs are settled.

There are certainly things to be settled for how the Gutenberg docs will be merged into the Core developer docs, one of those things will be determining how we ensure APIs have an @since tag, so you can easily see when an API was added or changed.

In the mean time, however, the best place to check on anything that seems confusing is in the #core-editor Slack channel.

[salcode]

I understand your point of view. Thank you for your consideration.

[salcode]

This problem has come up once again and while this issue is closed, it seems appropriate to still document this occurrence.

The RichText component has been moved from wp.blocks.RichText to wp.editor.RichText and the documentation is updated to reflect this.

The result is the official documentation is ahead of the current release.

The currently published example code in the official Gutenberg handbook references wp.editor.RichText and therefore does not work with the current release of the Gutenberg plugin (2.8.0).

[noisysocks]

Could we have the documentation pull from a release tag which is updated during the release process (e.g. using git tag -f release)?

[danielbachhuber]

@noisysocks Good suggestion. That seems like a very reasonable approach, given the constraints involved.

[danielbachhuber]

Per Slack conversation, we're going to punt on this again.

API changes should happen less and less as Gutenberg stabilizes. Tracking documentation to the master branch means documentation improvements will go live as quickly as possible, which is valuable for our current needs.

If this issue still presents itself as a problem in the future, we can re-evaluate at that point.

[chrisvanpatten]

With the try callout coming and a number of (mostly small) API changes still in the pipeline, I wonder if it's worth revisiting this. Increased dev attention might lead to confusion on this.

[maddisondesigns]

I just tried adding in theme support for editor-font-sizes into my theme. After spending time trying to get it working and wondering why it didn't, I raised an issue (#8286) assuming it's a Gutenberg problem. @chrisvanpatten advised me that this feature won't be in Gutenberg until v3.4 and that the Gutenberg handbook docs reflect what's in master, not what's in the latest plugin release.

This is the first time I've heard that and there's nothing in the docs that mentions this either.

This is really confusing for developers trying to support Gutenberg in their plugins/themes. I'd like to make a couple of recommendations:

1. Can you please put a big notice at the top of the Introduction page advising people of this. Something like "PLEASE NOTE: This Gutenberg handbook documentation reflects what's in master, not the current plugin release."
2. When a new section is added, such as "Block Font Sizes", also add what version it's available from. There is nothing in the docs at the moment that gives any indication as to what is available now or what is available in the next or following releases.

[HelaGone]

Currently testing wordpress 5.0 beta 5 and RichText is not working as suggested in the docs. Getting this error: TypeError: Cannot read property 'RichText' of undefined. #6745

[crilleengvall]

@HelaGone I'm also trying the latest beta. I've found that i could get hold of the RichText inside the save and edit functions. Like so:

    save( { attributes } ) {
      const { content } = attributes;
      const { RichText } = wp.editor;
      return (
      <RichText.Content
          tagName="p"
          value={ content }
      />
      );
    },

This is the first time i'm using Gutenberg so I have no clue if this is correct or wanted behaviour. But at least it displays a RichText :)

[HelaGone]

@crilleengvall While your solution actually works, I found that it is way better if you install the component yourself like so:

npm install @wordpress/editor --save

Here is the documentation:
https://wordpress.org/gutenberg/handbook/packages/packages-editor/
This has to be done inside your block plugin and then import the RichText component this way:

import { RichText, } from '@wordpress/editor';

[crilleengvall]

@HelaGone Thanks! It was something like that i was looking for.
I was coming from this page which uses the RichText before it mentions how to reference it in the link you pasted: https://wordpress.org/gutenberg/handbook/blocks/introducing-attributes-and-editable-fields/

[HelaGone]

Are you building your blocks with some toolkit like create-guten-block? If so, they already have fixed the problem as described in this thread: https://github.com/ahmadawais/create-guten-block/pull/106.