Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix(docs): Update the create a source plugin tutorial #36862

Merged
merged 6 commits into from
Oct 24, 2022

Conversation

KyleAMathews
Copy link
Contributor

Did an initial pass on improving the tutorial. Some notes on additional changes I think should be made:

  • we really need to make the mental model clear for what a source plugin is. Having talked to a number of people in process of building a source plugin, they're often missing understanding of even very basic things. So similar to the main tutorial we should have people go step-by-step through the whole sweep of the data layer e.g. the different actions, showing them the LMDB file on disk, etc.
  • the example needs to a lot simpler — Apollo, etc. gets in the way of understanding things. Plus we should steer people towards Got
  • the tutorial mixes basic & advanced features — we should separate the basic tutorial from advanced features like relationships, images, content sync
  • make really clear how node caching works i.e. that nodes stay in the db until they're deleted (or not touched). This comes up over and over.
  • relatedly: make really clear how to do delta syncs. This also is rarely understood and comes up over and over
@gatsbot gatsbot bot added the status: triage needed Issue or pull request that need to be triaged and assigned to a reviewer label Oct 21, 2022
@KyleAMathews KyleAMathews added status: needs docs review Pull request related to documentation waiting for review and removed status: triage needed Issue or pull request that need to be triaged and assigned to a reviewer labels Oct 21, 2022
DSchau
DSchau previously approved these changes Oct 21, 2022
Copy link
Contributor

@DSchau DSchau left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems very sensible!

Co-authored-by: Dustin Schau <DSchau@users.noreply.github.com>
@LekoArts LekoArts added type: documentation An issue or pull request for improving or updating Gatsby's documentation and removed status: needs docs review Pull request related to documentation waiting for review labels Oct 24, 2022
@LekoArts LekoArts merged commit 2b8c2f2 into master Oct 24, 2022
@LekoArts LekoArts deleted the source-plugin-doc branch October 24, 2022 06:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
type: documentation An issue or pull request for improving or updating Gatsby's documentation
3 participants