Several issues with the documentation.

[OdifYltsaeb]

Preliminary Checks

• This issue is not a duplicate. Before opening a new issue, please search existing issues: https://github.com/gatsbyjs/gatsby/issues
• This issue is not a question, feature request, RFC, or anything other than a bug report. Please post those things in GitHub Discussions: https://github.com/gatsbyjs/gatsby/discussions

Summary

I have several issues with the documentation. They are misleading, there is not enough information, they are not up-to-date or there are other things missing.

Background - I'm using docker image (wordpress:latest) and gatsby generated with gatsby new my-wordpress-gatsby-site https://github.com/gatsbyjs/gatsby-starter-wordpress-blog

1). https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-source-wordpress/docs/tutorials/configuring-wp-gatsby.md says: You will see 5 fields related to Gatsby Preview. "Enable Gatsby Preview?", "Use Gatsby Content Sync?", "Content Sync URL", "Preview Webhook", and "Preview JWT secret". If you do not see "Use Gatsby Content Sync?" you're on the latest version of WPGatsby and this field isn't needed. While in fact the WP-gatsby 2.3.3 has 6 fields. There is no "use gatsby contact sync" field.

2. The information about how to configure and enable the gatsby preview is lacking. The image mentions HTTP://localhost:8000/__refresh as refresh hook, but mentions nothing about having to configure ENABLE_GATSBY_REFRESH_ENDPOINT .env.development. The documentation should link here: https://www.gatsbyjs.com/docs/refreshing-content/

3. After enabling the gatsby preview and turning the refresh endpoint on, the gatsby previews still don't work. The __refresh endpoint seems to be working when you run curl -X POST http://localhost:8000/__refresh. But ONLY if you do not use the preview button but "UPDATE" button and run the curl command against the __refresh endpoint manually. So I'm guessing the documentation is lacking something else here also.

Suggestions on how to improve the documentation:

1. Clear and complete documentation per feature.
2. Include updating documentation into your feature acceptance routines
3. Occasionally try having someone set things up using the documentation only (maybe watch this: https://www.youtube.com/watch?v=Ct-lOOUqmyY) and see if they succeed or not.

Steps to Resolve this Issue

...

[tyhopp]

Hi @OdifYltsaeb, PRs that improve docs are welcome and encouraged!

[OdifYltsaeb]

Sure thing. I can only add & improve documentation on the first 2 points, though and since the current documentation is lacking, I have not been able to get the third point working myself. That, apparently, will take more investigation.