document machine-extractor and shared packages

[with-heart]

The @xstate/machine-extractor and @xstate/tools-shared packages are fairly powerful packages that could eventually serve as the foundation for a universe of XState-focused open source libs/tooling.

imo, we're just barely scratching the surface of what could be possible if we make it easy for anyone to translate between XState and ASTs/metadata

Unfortunately, the system currently feels pretty inaccessible. Which is totally fine! Not meant as a criticism in any way, that's just how it goes when you're building stuff.

That said though, I'm moderately knowledgeable in both babel and ASTs and it still took me quite awhile to wrap my head around the various pieces to the point that I could make any large-scale changes.

I'd like to propose creating at least entry-level documentation for these packages. A few reasons:

• Forces us to define a clear public api

  It's still early with these packages, but I think it's better to start thinking about this sooner rather than later. Hard to think about it when it's not even clear what that api is, which documentation will help us discover.

• Makes the packages more accessible to consumers or contributors

  I think this is important because more consumers = more feedback = better ideas + more paths forward, and similarly more contributors = more contributions + feedback = faster paths forward

• Allows us the chance to define a language for some of the patterns and workflows the libraries use in order to achieve their outcomes

  An example of this is the parseNode key of the createParser options object as mentioned over here by @Andarist. That name tripped me up quite a few times. Writing documentation will help us find this type of ambiguous or confusing language and replace it with more clearly-defined terms.