Gatsby: [docs] add Lifecycle Sequence, and then Diagrams

[sw-yx]

Summary

The current Lifecycle APIs docs page is pretty sparse. The Reference/Node APIs are autogenerated from jsdoc which is SWEET because it is likely to be up to date, but not so sweet because it is in alphabetical rather than chronological order. Also its not clear what are "major" lifecycles and what are less important.

I wrote up this gist from my own investigations, but it would probably make sense to have this in the docs somewhere as people found it useful for bug tracking/plugin creation.

Decisions to make, assuming we want this in the docs:

1. I think it would make sense to just put up and iterate on an all-text sequence, and then eventually make charts once we agree how best to represent this?

2. The other big choice to make is autogeneration vs manual maintenance. I suspect it may take more effort to do the former than the latter.

btw: please tell me if these kinds of open/discussiony issues are welcome, I'm actually not sure since this channel is also for bugs and stuff.

[KyleAMathews]

Very helpful! We definitely want to do this so appreciate you kicking off a discussion. /cc @kkemple @shannonbux

[kkemple]

Yeah this is very much aligned with what we are already planning! for me, I would personally prefer to use manual vs auto-generated for many of the reasons you mentioned, but also because docs like that do fit under API references but are a bit cold for guide type docs.

I will take a look at your gist today and I love the idea of just getting a PR up and then just iterate until we are happy and then build any visualizations off of that. Would love to eventually get to something like this:

[shannonbux]

Yes, very interested in this because I'd say it is one of the most common questions about Gatsby: "what is Gatsby?"
"what is Gatsby doing under the hood?"
"how does Gatsby work?"

So I know those are big questions! People want this!

[sw-yx]

well I can put in a few words then and we can slowly add to that. I think the problem with this kind of thing is its a deep, deep rabbit hole. the more detail people want, they more they basically just have to go through the source code. so we have to strike a balance somehow.

(concurrently I also think the console output itself needs to be redesigned.. which will make -this- effort a lot easier)

[m-allanson]

I love the idea of just getting a PR up and then just iterate

👍 to this

concurrently I also think the console output itself needs to be redesigned..

and 👍 to this!

[sw-yx]

sorry I know I come up with a lot of ideas for work. I will try to pr some things to balance it.

[KyleAMathews]

Adding this tweet to the conversation https://twitter.com/sebmarkbage/status/1012157736753098752?s=19

[tsiq-swyx]

wrote out some stuff, please edit if factually incorrect but this is my judgment of balance between detail vs keeping it high level.