📚 Docs Wish List

[davidkpiano]

Inspired by #255 (comment) and other conversations, both online and in person:

What would you like to see in the documentation? Let's keep a running list of things that would be beneficial to:

• developers brand new to statecharts
• developers wanting to create new apps/programs with statecharts
• developers wanting to refactor existing apps with statecharts
• experienced developers who want to do more with statecharts (e.g., more powerful type assertions, analysis, testing, etc.)

Some suggestions for things that can be included:

• philosophy/guides on how to "think" in statecharts and the actor model
• example applications
• when to use certain features, like guards or services or actors or transient transitions etc.

Current suggestions:

• TypeScript section for each guide
• Convert examples to TypeScript
• Best practices page/section
• Glossary
• Patterns and architecture
• "Build your own" XState (machines, Actor model)

Please post your suggestions 👇 Thank you!

[nick-walt]

I'm becoming familiar with the Xstate Docs and really like their style and format. However...

While the sections focus beautifully on implementation details there is virtually no mention of patterns and architecture (other than indicating a relationship with the Actor model).

If there is one thing that (I believe) helps new learners (especially beginners) it is being able to understand implementation details clearly within the context of patterns and architecture - and in relation to other patterns and architecture.

The Redux Docs are an excellent example of this presentation of detail in context. These two articles, by the same author of the Docs, provide even more context and opportunity for understanding the why's and how's:
https://blog.isquaredsoftware.com/2017/05/idiomatic-redux-tao-of-redux-part-1/

https://blog.isquaredsoftware.com/2017/05/idiomatic-redux-tao-of-redux-part-2/

I know how hard it is to write good documentation but I think this kind of addition would be of significant benefit. I believe that it would dramatically improve comprehension.

I would like to help if there were an opportunity. Even if it was to give feedback from a beginner's level.

[nick-walt]

In my current thinking I see functional programming as a natural fit with both unidirectional data flow and reactivity to observed state changes.

But because of my lack of experience I have attempted to find documentation that could help me understand how Xstate's Actor + FSM architecture might be understood in contrast with this view.

I could not. I couldn't see if we were being asked to abandon a unidirectional data design and, if so, why.

What also added to this question is that Xstate seems somewhat unique in its own implementation of the Actor model due to being also reactive and functional.

Functional programming and reactivity did not seem to be native to the various Actor models I was reading about. Those Actor variants appear to promote messaging rather than reactive streams, and an object model over functional model.

What I saw in Xstate's Actor was a many-to-many message passing model. But this does not appear to be reenforced and clarified in the implementation details throughout the rest of the Docs.

While looking for insight into these questions (and many others) I have also attempted to understand how Xstate messaging might be wired up to Svelte's native reactivity.

I had no ground on which to stand and orient myself amongst all of this.

[nick-walt]

What I see as another natural fit for functional, reactive programming (and the basis of a unidirectional architecture) learning about the CQRS/event sourcing model influenced me significantly.

In the absence of being able to read more in depth about Xstate's own patterns and architecture, I could not come to any understanding or relate it to what else I was learning about.

However, this document seemed to indicate a natural fit between the Actor model and the CQRS/event sourcing model:
https://doc.akka.io/docs/akka/current/persistence.html

[yungcky]

The approach to developing an entire application whether in functional or actor model are entirely different paradigm. If choosing actor model, functional programming can still be implemented but within the context of an Actor as reusable business logics triggered in Xstate. This approach harness the best of functional and actor programming. Just my opinion.

[avaragado]

A few thoughts on tech writing in general that might be useful. Apologies if this is all blindingly obvious to you.

• Know who you’re writing for. It’s fine to have some parts written for audience A and some for audience B, but don’t mix them. If you (as the writer) don’t know who you’re writing for, readers will struggle. Be ruthless: in a piece intended for users new to the topic, a deep dive, even as an aside, will alienate.
• A high-level “10,000 foot” view helps to orient readers: main concepts, important terminology, problems solved. It’s also great as a refresher for returning users.
• Every extra piece of terminology is an additional cognitive load on a reader, and might conflict with the same term used elsewhere. If it quacks, it’s a duck: inventing a new name confuses more than helps. Where overloading is necessary (here, perhaps because SCXML defines a term) highlight the differences from typical usage somewhere handy like a glossary. For example, action and event overlap somewhat confusingly with Redux.
• Examples are incredibly helpful and, because users typically avoid reading, often the only “documentation” they’ll actually look at. Good examples are hard to write. Adding to an earlier example - annotating the code with the changes - reinforces the earlier example and doesn’t force the reader to get their head around entirely new code before they can grasp the point you’re making with that example.
• If you write a sequence of steps, work through them yourself manually, from the same starting point as your readers. Follow your own steps literally and exhaustively, adding and subtracting nothing. Copy and paste code samples, don’t retype. It’s amazing how often you find mistakes and hidden assumptions that you need to mention.
• For anything intended to be read in sequence - such as a multi-page tutorial - the cardinal sin is to casually use terms you haven’t introduced. These are tricky to spot as you’re familiar with everything already.
• Worry about the learning curve. Too much documentation jumps from simple to complex - from the perspective of your audience - without anything in between. (“Turn on your computer by pressing the power button. Then spawn a shell and vi your hosts file.” If I know what sentence 2 means, sentence 1 is redundant. If sentence 1 is necessary, sentence 2 might as well be Martian.)
• Use simple English. Avoid Latin (eg, ie, etc). Avoid humour. Shorter is generally better.
• Never say “of course”. What’s obvious to you isn’t necessarily obvious to your readers, and can appear smug or patronising. Similar: “it’s really easy,” “don’t worry,” “simply/just do XYZ.”
• Prefer active not passive sentences: “the machine enters state Y” is easier to read than “state Y will be entered [by the machine]” especially for those whose first language isn’t English.
• What, why, who, how, when, where. Keep these in mind at all times. The most common omission is “why”. Why is this important? Why should the reader care? Why does the code do that? Why won’t ABC work?

[ajmueller]

@avaragado I just randomly came across this discussion and noticed all of the thumbs up and hearts on your comment. After reading it, I must say that they have been earned and then some; I added a thumbs up and heart of my own, for whatever they're worth. I have a "cheat sheet" of random tips, tricks, and commands that I keep for my development work and these have all earned a spot on that list. As such, I thought I'd stop and say thank you for taking the time to write this. Documentation is so hard to write and each and every one of these bullet points is a worthy aspiration for any good piece of documentation.

[avaragado]

Thank you!

[CodingDive]

I want to start by saying that I really love the documentation already.

I would love to have more documentation or examples on TypeScript. Which types to use when passing an actor, service, just a send function, etc. as argument. Converting the examples to TypeScript could also help and on top of that would encourage people to use it with XState.

Another thing that could be useful is a best practices page where tips are shared on how to write optimal machines. XState is very flexible when it comes to which types it allows for any given key. It would be great to have a dedicated page that shows which ones should best be used for optimal visualization, readability and refactoring.

In the docs, an example of this can be found for actions

Always prefer refactoring inline action implementations in the actions property of the machine options, like the previous example.

A page with reserved xstate keywords like actions, states could also be useful.

[davidkpiano]

I would love to have more documentation or examples on TypeScript

Each section in "guides" (when applicable) will have a TypeScript section. I'm also working on simplifying TypeScript types.

Converting the examples to TypeScript could also help and on top of that would encourage people to use it with XState.

Great idea. I should make some sort of toggle between TS and JS for the code examples.

a best practices page

I'm making "Tutorials" that shows the best practices in practice, but afterwards I can compile a summary of the best practices. It's just weird (for the reader) to see best practices out of context (e.g., "always avoid this" without a reason why, or an exception).

A page with reserved xstate keywords like actions, states could also be useful.

Like a glossary? Good idea.

[CodingDive]

Yes, a glossary of xstate reserved keywords in machines sounds good.
Such list could then also be used to create a vs code extension which syntax highlights the xstate keywords.

[nick-walt]

It may be helpful to have guidance on how to implement the core of Xstate - its machines and charts - into existing state management patterns and architectures as well as having guidance on adopting the Actor model and Xstate's own state management paradigm.

[davidkpiano]

Pure state machines and actor model, sure. Statecharts are a complex algorithm. See for yourself: https://www.w3.org/TR/scxml/#AlgorithmforSCXMLInterpretation

[nick-walt]

I've updated my above post to mean Xstate's machines and charts.

[abierbaum]

I just found this library today and have gone read all the documentation. First thing I want to say is thank you so much for the quality of the documentation already. It is excellent. Some of the best I have seen. A couple things I would like to have seen:

• A high-level summary of all the concepts in a single page or two to help orient to the terminology and what is possible. (something like: https://angular.io/guide/architecture). I think this would help orient new users and also help experienced users to see a big picture view and then zoom into what they need.

• A single place that shows all configuration options for a machine on down through each piece. So for example I can't seem to find a place that shows me every option I could use inside of a state node in a machine definition. Another way this could be done is maybe a cheat sheet that shows the various options for all the pieces in the machine configuration and references the other items on the page.

• A recipe for how to use a interpret'ed machine inside an object. I am coming from a typescript and angular background. I am looking for a way to add a state machine inside some of my more complex services. The machine isn't the entire service, it is simply helping to keep track of some core state in the service. How would I make use of the state machine inside of an object and allow the transitions and actions to make calls on the object? How should context be setup, should it provide a reference to the object for making side-effects?

• Provide insight as to the "why" for certain features. For example while reading through the documentation I would see things like delayed events and think, well that looks pretty interesting. But It wasn't always clear why or where that would be useful. I think discussing it in terms of problems or issues that the features help solve would help people make sense of when and how to use certain features.

• Use typescript in some of the examples. Typescript is awesome, the more of it the better.

[jjenzz]

I feel a bit silly posting this but one thing I struggled with was deciding whether something should be a state or a guard.

My initial understanding was that you declare events in a specific state to "guard" them and transition to those states under correct conditions. However, we can also declare events inside a state that it shouldn't always be able to fire in and use an XState guard to validate the condition before firing. For example:

const machine = Machine({
	id: 'myMachine',
	initial: 'form',
	states: {
		form: {
			on: {
				INPUT_THING: {
					actions: ['setThing'],
					target: 'valid'
				},
			}
		},
		valid: {
			on: {
				SUBMIT: ['handleSubmit'],
			}
		}
	}
});

versus:

const machine = Machine({
	id: 'myMachine',
	initial: 'input',
	states: {
		form: {
			on: {
				INPUT_THING: {
					actions: ['setThing'],
				},
				SUBMIT: { 
					cond: 'isValid',
					actions: ['handleSubmit'],
				}
			}
		},
	}
});

I ended up going with the latter for my particular implementation because the valid state almost became a replica of the form state but I wasn't entirely sure if I had made the right decision there or how you would decide to choose one over the other upfront.

[jjenzz]

Never say “of course”. What’s obvious to you isn’t necessarily obvious to your readers, and can appear smug or patronising. Similar: “it’s really easy,” “don’t worry,” “simply/just do XYZ.”

Aw man, this made me re-read some of my blog posts and I have a simply/simple addiction it seems. Need to go away and reword some things 🙈

Thanks @abierbaum. Great write up and suggestions. I'd like to highlight your last point:

What, why, who, how, when, where. Keep these in mind at all times. The most common omission is “why”. Why is this important? Why should the reader care? Why does the code do that? Why won’t ABC work?

I've struggled with the "why" in particular from the XState docs. I'm a fully self taught dev so don't have a CS background or any previous experience with State Machines. Some of the concepts/terminologies are a bit hard to grasp and understand the "why" for me at the moment.

Actors, for example, seem to provide pub/sub communication between machines but this appears to introduce a bidirectional data flow. With React, I'm used to data down, actions up so why would I choose Actors over what I'm used to? Also, is there any harm in just mapping machine actions to React component handlers for that communication?

const Parent = () = {
	const [machine, send] = useMachine(parentMachine);
	
	return (
		<Child 
			thing={machine.context.thing} 
			onChange={event => {
				send({ 
					type: 'INPUT_THING', 
					payload: event.target.value 
				});
			} 
		/>
	);
};

const Child = ({ onChange }) = {
	const [machine, send] = useMachine(childMachine, {
		actions: {
			handleChange: onChange
		}
	});
	// etc...
};

It feels this would keep component concerns separate and appease my unidirectional flow preference, but it's not clear if that would make my machines brittle in some way and if we should stick to Actors for that reason.

[stutrek]

Thanks for this library, I'm having fun learning it and I plan on switching to it for my side projects.

I would like to see documentation of all the options that can be passed to each state, service, etc. Right now I find myself looking through the docs for an example that does what I want, and often finding it as part of an unrelated example.

Add a link to your React Conf 2017 talk, it's the one that sold me and my coworkers on state charts. The price of the book you mention in the talk has fallen to just over $100.

Things I'm struggling with:

• Figuring out parent/child machine relationships and useService is hard. I want to put machines with the components that use them, but I am having trouble figuring out how a machine as a service relates to the parent machine's state from useMachine. I also find calling a machine a service confusing, parent/child makes more sense to me.
• States have tons of options, but there's no bullet list of them.
• examples. There are only like two and they're quite small. I don't trust that I should be doing things like the todo example.

[jjenzz]

https://spectrum.chat/statecharts/general/statecharts-watercooler~4c9e9fb0-74be-4ae0-bf56-e0fcfba903b4?m=MTU2MjkzNDY4MDU5NQ==

That receiving actor can never update that local state directly

This was helpful in clearing up my Actors confusion. This was also a lovely simple explanation:

https://spectrum.chat/statecharts/general/statecharts-watercooler~4c9e9fb0-74be-4ae0-bf56-e0fcfba903b4?m=MTU2MjIzOTA1NDI0NA==

[ezhikov]

So, I was directed here from twitter. I'm experimenting and tinkering with XState since David gave talk on Holy.js. Then I read the docs for few days (not full days, of course, but it took plenty of time).

What I really liked

I, personally, love deep dives into every concept covered by docs. I love to know how things work and what they mean. Examples for each concept is pretty sufficient as illustration. They applicable for modeling purposes, but not for using libary in apps.

What was missing

When I tried to apply different concepts from guide to some problems that I had in real world it was hard to do so, since every attempts generated more questions that experience. Later I understood that I tried to apply wrong parts to wrong problems. That would be great to illustrate some applications for different concepts on when to use them. Not sure that's possible, though, but understanding when you need parallel state vs actor can be really helpful for someone just starting with statecharts. For example I still don't understand when to use invoke and when to use spawn, apart from automatic cleanup in former case.

Not sure how to properly explain this bit in any language and especially in english, so sorry if it's look like gibberish. Another thing that was helpful for me is understanding that with statechart I don't need to model solution to my problem, but instead should model the problem itself. My initial thoughts on this library was "Wow! It automatically solves half of my problems and, probably, it will solve much more", so I started to write solutions with XState and not models for my problems.

Something like conclusion

For me documentation was enough to understand meaning of various parts, and deep enough to serve as a base for further exploration. The only thing that gives me hard times is Actors, but it's not about XState docs - every explanation of actors that I encountered for me looks like "Simple... Simple... Math and Physics which I lack education on". And after reading about all concepts and possibilities it was pretty hard to decide when and where to apply this. If I'd saw this tweet at the very beginnig, I'd be more comfortable on transition from synthetic examples to real code. I think it would be great to give some minimum for start and then proceed to advanced topics for when simple stuff is not enough anymore.

Anyway, that's great library and documentation that shifted my perspective in a good way.

[ezhikov]

Oh. I completely forgot about trouble I had with @xstate/test. It's unclear that you might not need to cover your application machine with tests, but rather should create simpler statechart from perspective of user for tests generation. I got help on spectrum, but was pretty frustrated initially.

[Blacktiger]

Something that multiple people on my team have hit is trying to use the null transition instead of an entry/exit transition. Without making the null transition target a new state xstate gets into an infinite loop and the error message isn't very clear about what really went wrong. That feels like something that should either be prevented, or it should be documented clearly not to use the null state in that way. Maybe something as simple as a big warning in the docs on the null transition to point the user at the entry/exit transition as a better solution would work?

[davidkpiano]

I think it would be good to add a warning if an eventless transition can get into an infinite loop. Can you share some example code where this is happening, so we can better identify the patterns?

[Blacktiger]

The following sandbox demonstrates. Though in this case I used always instead of "" since that's deprecated now. Deprecating the empty string version in favor of always might help people identify a potential mistake but I still think it's not necessarily obvious why the infinite loop is happening (especially once the machine is more complex than this simple example). https://codesandbox.io/s/serene-einstein-ej1ns?file=/src/index.js

[Andarist]

It should be fairly easy to extend this validator to identify this kind of a problem:
https://github.com/davidkpiano/xstate/blob/2fd0ee24dbad8aec69ed2ab003c2e6c1c3f50f1f/packages/core/src/StateNode.ts#L116

I think for starters we'd have to check against unguarded, targetless & eventless transitions. This should cover most situations I think.

[davidkpiano]

@Andarist Want me to make an issue for tracking this?

[danielkcz]

I would love to see in docs some summarization of what service.stop() does. Just learned it also cleans listeners for onTransition and others. That's a very important piece of information because of a rather inconvenient API (#1531) for these listeners and cleanup.

[davidkpiano]

Sure, I can add that. In general, it cleans up all listeners and recursively stops all spawned/invoked actors.

[Andarist]

@FredyC even if it didn't clean those listeners the registered callbacks could be cleared up by the garbage collector - if you would dispose of a reference to the service itself but probably most of the times you do after completing some temporary work involving a service (or anything else), so this fact isn't that important really. Compare it to promises - you never have to cleanup their listeners manually and in a similar way, there is no much need to clean up them in a case of service here (unless you, of course, want to stop listening while the service is "alive" and running).

Much more interesting is the fact about stopping children etc.

[tomByrer]

• FSM comparable API flags

XState has quite a bit of the same API as FSM. I'd like to have some kind of marker or filter to the entries in the XState docs that are FSM compatible.

In general, more simple examples help.

Thanks so much!

[davidkpiano]

That's a good idea!

[megleighc]

Apologies if someone already mentioned this - it would be really helpful to have more verbose docs and possibly step-by-step examples on how to setup unit tests for machines - both with @xstate/test and existing testing frameworks!

I've been attempting to read through the testing section of the docs as well as the discussions here and in the original Spectrum community but it gets a little overwhelming trying to locate examples and wrap my head around what to do.

[davidkpiano]

This was recently added re: unit testing machines: https://xstate.js.org/docs/guides/testing.html

[megleighc]

Thanks, David! I had reviewed those and they were helpful for how to test the machine itself but I'm still lost on what to do if I need to test a React component (or nested React components) and the machine it uses - if that makes any sense.

[Blacktiger]

On my project we just use jest mocks to mock out any services the machine has to call and everything else just works in general. You can even use a promise with no resolution to mock out loaded states if needed.

EDIT:
If you use useService you can pass in a mocked machine as well but I don't like that approach myself.

[davidkpiano]

Adding this Twitter thread here: https://twitter.com/mpocock1/status/1345083512173555712

[with-heart]

I wanted to share what I consider one of the best documentation system resources available: https://documentation.divio.com/

This image encapsulates the big picture ideas presented:

Each quadrant has a rather particular way that the documentation should be written and presented, because each accomplishes a different outcome and targets different types of users.

I think XState's strong point right now is the reference quadrant. The documentation is mostly an API reference, and it does a good job covering the vast majority of the API and how it works. This is great for people who already have a decent understanding of XState and want to turn to the docs for a quick refresher on how exactly something is used.

For the other three quadrants, I think there are bits and pieces of each scattered throughout the docs, but for the most part, they're nonexistent. This is especially hard on new users, as the learning curve can be quite drastic due to a lack of resources that hold your hand as they help you build something/teach you the high-level concepts, a lack of quality examples (though XState Catalog is SPECTACULAR at filling this gap), and how-to guides around how to take those concepts and produce something of value.

Essentially, API reference gives us the what, but we're missing the why, when, and how.

In my opinion, I think XState would be best served by considering each quadrant as a separate platform-within-a-platform. Keeping the content for each quadrant separate allows users to easily access the type of content that works best for them, while also allowing for easy linking between the sections (a tutorial linking to an explanation page for more detailed information than is relevant to the tutorial, an API reference page linking to a how-to guide that utilizes that part of the API, etc.).

[with-heart]

@mattpocock had linked to the Redux FAQ and I think it's a really great example of the "explanation" quadrant. It answers specific questions in order to provide a conceptual understanding of how Redux works under the hood. Combined with the "Understanding Redux" section of their docs, a user can get a significant amount of conceptual information about the framework.

[cqh963852]

Agree with the idea.

When I am looking for a quick start. just for a counter. But The Guides route is much higher than Tutorial route.

In the document, the Guides much like EXPLANATION.

I have to search on google xstate counter... then link back to the document.

[with-heart]

Wanted to share some topics that were discussed in the Discord #documentation channel today:

• @ChrisShank shared the idea of integrating learning tools into the documentation. He linked to Orbit as a possible tool and shared a post by Andy Matuschak that documents the concept behind it while demonstrating it as part of the post.
• I shared some thoughts around the difficulty of writing documentation for beginner/intermediate users as a maintainer and maturing documentation alongside a project.
• jonathanj shared the idea of using actual machine code as a map for the library's documentation by rendering the various pieces of the machine config as hyperlinks to their respective docs pages.
• @mattpocock thinks the goal of the documentation should be two-fold: a first-class api reference that's as interactive and api-focused as possible, and a first-class onboarding tutorial as good as Svelte's.
• dhirj thinks it would be helpful if we shared/collaborated/iterated on a tutorial content outline.

[rsinohara]

I am just coming in for a few weeks now. I think most topics haven't yet 'clicked', but they will eventually.
I somehow feel that I have been approaching topics the wrong way.
So I am trying to build small applications, side by side (implementing them both with XState and without).

Then it hit me: we all probably have a few of those. Could we list them somewhere, I feel that this could be a valuable resource. And it can show the difference state machines can make.

[youmustfight]

A pattern page for spawning machines and passing data between them? I know a lot of people especially in legal/social services need flows that collect and validate data in heavy ways. That was something I found hard when first getting started, but I feel like I settled on a really nice flow in re-writing upsolve.org's data collection questionnaires with XState, and would like to share to help others

[dsathyakumar]

@davidkpiano an example of testing a react component with xstate by mocking invoked services would be very helpful. Thanks.

[hendrul]

• I would love to have a more readable version of the API docs, I don't like so many typings on a documentation, that makes it unreadable
• An API cheat sheet

[bartenra]

In machine.md activities are mentioned, but when I checked the relevant section, I see that they are deprecated.

It should probably be removed because it is confusing when reading the docs sequentially.

[davidkpiano]

PR here: #3100

[jzecca]

+1 for a better TypeScript & best practices documentation.

I'm currently upgrading an app from XState 4.16.
I read changelogs, docs & examples... and the best term to describe what I feel right now is JavaScript fatigue 😕

So far, here is what bothered (or still bothers) me the most:

When it comes to typing machines:

• The Models section affirms that createModel "is meant to improve the developer experience"
• The TypeScript section is all about using schema
• ...and typegen, which is flagged as experimental AND requires either a VS Code plugin or a CLI
• Most examples aren't using any of those 3 but generics (I'm looking at you, template-ts)
• ...while some others use createModel
• In the discussions tab, I find out that "We don't recommend using createModel - typegen supersedes it."
  AFAIK, this is not stated in the doc.

Regarding Typegen

Even with a (very) basic understanding of the "why?", the whole "let's add one more plugin/CLI to the dev's tooling" feels like terrible DX imho.

Even if it comes out great, it's still an extra pain to setup (plugins are a no-go since I want my team members to be free to use whatever IDE they see fit).

I might have missed something, but I think some explanations (and maybe a setup guide) might be a great addition to the doc.

Regarding testing

• waitFor and SimulatedClock should probably be at least mentionned in the Testing Machines section, as they're a great help for testing.

• I had a really hard time (and finally gave up) to understand how to use @xstate/test to test a state machine, especially without an UI.
  Maybe it's me though 😉

Exports

Definitely not a big deal, but exports lack consistence, and the doc reflects it.

Right now, there's 3 (!) ways to import actions for instance:

• Using direct exports, as in the Assign doc
  This is the nicest solution imo, but only a few actions can be imported this way.

   import { assign, send } from 'xstate';  // Yep!
   import { escalate } from 'xstate';      // Nope.

• Destructuring actions, as in the Escalate doc
  Destructuring is awesome, but I'm not a big fan of it when it comes to imports.

  import { createMachine, actions } from 'xstate';
  const { assign, send, escalate } = actions;

• Using /lib to avoid destructuring
  Not found regarding actions, but this is how createModel is imported in the doc.

  import { assign, send } from 'xstate/lib/actions';

And that's all... for now 😄
Hope it helps!

[mattcroat]

Introduction

I apologize if I'm repeating some points that have been said here but here's my feedback from the perspective of a beginner that has read the current documenation and beta documentation for XState.

Praise

First I need to praise the introduction to state machines and statecharts because it's an absolutely wonderful introduction even I could understand.

The Docs Leave You Stranded

After the introduction I'm excited and want to learn more.

I continue reading about Machines which introduces a nice basic example that shows how to define a basic state machine but unfortunately here is how most examples end up being frustrating because it leaves things to the imagination.

import { createMachine } from 'xstate'

const lightMachine = createMachine({
  // machine identifier
  id: 'light',

  // initial state
  initial: 'green',

  // context
  context: {
    elapsed: 0,
    direction: 'east'
  },

  // state definitions
  states: {
    green: {
      // ?
    },
    yellow: {
      // ?
    },
    red: {
      // ?
    }
  }
})

// how do I even make this work?

After that point the docs leave you stranded because to get a basic example working you have to piece the information together yourself from different sources — the examples are more for documenting the API instead of guiding you as the name of the section implies.

I scour the docs and the internet to piece the information together which I don't mind honestly but I would prefer if you could level up step by step reading the docs and get that dopamine hit.

After reading more of the docs I feel confident I can make something basic and I reach for the high IQ counter example of course.

Sounds great but here is another example where I feel the docs fail you for the same reason having to piece the information together yourself which feels like work instead of being a fun learning experience.

const counterMachine = createMachine(
  {
    initial: 'active',
    context: { count: 0 },
    states: {
      active: {
        on: {
	  INCREMENT: { actions: 'increment' },
	  DECREMENT: { actions: 'decrement' },
	},
      },
    },
  },
  {
    actions: {
      increment: assign({ count: (ctx) => ctx.count + 1 }),
      decrement: assign({ count: (ctx) => ctx.count - 1 }),
    }
  }
)

If I'm feeling spicy I might even throw in a guarded transition but so far I'm pleased and I learned earlier I have to interpret the machine and start the service using regular JavaScript.

const counter = interpret(counterMachine).start()

Awesome! Now I just want to simply output count when it changes. That shouldn't be hard right?

const incrementEl = document.querySelector('.increment')
const decrementEl = document.querySelector('.decrement')
const countEl = document.querySelector('.count')

incrementEl.onclick = () => counter.send({ type: 'INCREMENT' })
decrementEl.onclick = () => counter.send({ type: 'DECREMENT' })

// ...

I spend more time looking through the docs to find what I missed hoping there's a similar example at least which there is but it's also incomplete and I find the solution from a random post.

counter.subscribe((state) => {
  countEl.innerText = state.context.count
})

No wonder this works like magic in Svelte.

I don't remember reading or seeing anything about service.subscribe until now and even searching for it I can't find it anywhere in the docs and I consider myself as a black belt when it comes to search.

After I'm done I jump into some of the tutorials and I'm faced with the same problem because it also requires knowledge hunting and gathering from before and there's examples but it's using a framework when the docs aren't using it in the examples and introduces more mental overhead.

I wish it wasn't that way because I can't imagine how it's for someone that's not even familiar with any of these concepts.

Hope this is helpful!

[davidkpiano]

Extremely helpful, thank you very much for writing this! I agree that the docs could use more love, especially when guiding new devs to being productive with it quickly without having to reach out beyond the docs.

[korniychuk]

sendParent() is absent in the documentation to XState v5.
It was hard to realize how to send an event to the parent without _parent. I found the function in the source code. Then found only 1 mention of it in the blog post.

[davidkpiano]

Added here: https://stately.ai/docs/actions#send-parent-action