Introductory websiteAugust 11, 2018 at 6:48pm (Edited 1 year ago)
This thread originates from a discussion with Erik on how to best introduce statecharts. This is a large subject, and this thread is more focused on possible improvements which could be brought to the existing website https://statecharts.github.io/. I reproduce excerpts of our private conversation and is happy to hear about your opinion.
Well actually it is not easy to copy messages with this chat, so I will just link to the history of the conversation for how it started and the premises : https://spectrum.chat/statecharts/introductions?thread=3317eda8-bd43-4b55-8c9d-018efc05ac67
August 11, 2018 at 6:55pm
We can continue talking about the website under a separate post, rather than your introduction post :)
I've toyed with the idea of a landing page like a product landing page, but I didn't want to scare people away, but yes, the idea has crossed my mind.
the way you present is nice, because it is presented almost like a research subjec
you include not only advantages but also tradeoff and for me that is a great plus as I am always skeptical about people only telling you the amazing sides of their technology
but still, it is a lot of words. I like words, and I like ideas, but I was faced with people who really think they can grasp a concept in 5mn (you know the how would you explain to a 5-year old kid syndrome). And to these people I think that just putting the claims out there is enough.
I mean graphql is Describe your data Ask for what you want Get predictable results
I think thats neat
and then four examples, with very little explanation
Take the Tutorial
escenic : Stable and flexible CMS for news sites :-)
so my interrogation now, is what would be a concise punch line for statecharts?
I could say something like : the shortest path from specifications to verifiable, reliable implementation
that emphasizes the productivity factor.
one could also aim to emphasize the good behaviour under iteration (what I call on my blog continuous design, by analogy to continuous functions - a small change in specs should be associated to a small change in implementation).
if you look at statecharts in safety-critical software, the idea is that once you have specified a chart, code is automatically generated, and the statechart can be formally verified or checked.
then of course the statechart is only a part of the equation there is a suite of tools behind it, but it is the core than enables all the other products.
so statecharts are specifications, which are so precise that they also are an implementation.
there should be a way to put that in a nice sentence
another example : LessAccounting – Bookkeeping, Without the Hassle.
statecharts : for UIs which just work, without the work to make them work
mmmm well maybe not, it is actually some work to precisely specify
:-) I guess our design ability is similar. I suck at design. But maybe we have design-minded people in the community? Wiki/blog style is not bad in any case. It is not directly so much about how it looks like visually, it is really more like if there is any (if possible easy) way to convey the why statecharts in a more forward way. For me there is the why and then there is a how. Thus my thinking around punchlines. I think the site is strong for the how. I think maybe the why can be strengthened. Those are two different goals though. One is about convincing skeptical or profane people to have a deeper look, the other is tutorial/documentation
I am still struggling myself to find a concise but still convincing answer to the why, a kind of an elevator pitch if you want.
how did you get to know about statecharts? Do you have any prior experience using state machines? in which context (UI, protocols, etc.) It would be good to hear from you what you liked the most with state machines and what convinced you to use it for the first time. All those experiences could find their way on the website in the shape of testimonials or else
I got into statecharts through the xstate library. It's a nice way to get into it because you can immediately start applying it and seeing all the benefits of statecharts.
So coming from that background, the statecharts website was really useful to me because while xstate was a nice low barrier-to-entry to statecharts, the site helped me understand the intuition behind what I was doing.
I see where you're coming from and if I just were introduced to the statecharts site without seeing xstate first then I might be a little turned off mainly because to learn I like to experiment with stuff rather than just read. But the xstate site sold me on statecharts mainly based on the Why section in the xstate docs (https://github.com/davidkpiano/xstate#why). After watching the video and playing around I immediately got it. I think trying to add some "marketing" (for lack of better word) to the statecharts site is tough because by nature it would be hard to sell me on it without the application through something like xstate.
The only thing I would suggest is to add a table of contents with grouping, like how the React docs are laid out. The glossary has breadcrumbs but besides that after following a few links it's easy to not know where you are on the site...
Would also say that even though the statecharts site might be wordy it's concise and understandable and I expect and prefer that. I don't see it as a product launch page, I see xstate (and maybe other statecharts implementations) like that.
Yes , you echo my feelings too, that it's not a product launch site. However, the main landing page should probably not look like a Google Doc. I dunno. This is one of those things that could be added as an A/B split test for a few months to see what "performs better" (just joking!!).
If anything, I'm going to add an interactive playground of some sort to the landing page, and on the 'what is a state machine' and 'what is a statechart' pages. The "what is a statechart" is the most visited page after viewing the front page, and it is one of the oldest pages on the site, and it shows!
When it comes to a table of contents, I've done without that on purpose, pushing whatever I have down in the footer, and clearly demarcated as such. The only exception I added was the breadcrumbs to the glossary. I want the content to be front and center, and not end up with a myriad of links. But I guess some form of signpost, like the breadcrumbs in the Glossary, would be beneficial.
The other reason there isn't any table of contents, is the organic nature of the site's growth; Every month or so, I'll add a few pages here and there, sometimes meandering, sometimes following a red line. A table of contents can only come after the content is there. So the next task is to try to fashion a table of contents of the content that is there, and then place it somewhere where it doesn't get in the way of the content :)
(btw, on the bottom of the glossary page for state you can see how I've highlighted the different types of states, just above the footer (under the see also header).
GraphQL style hero code block:
* Describe your behaviour (little xstate snippet?)
* Send events (
* Get predictable results (
It's also tantalizing that both statechart and statecharts are available in the
.com top level domain
that is not bad. though the last one
get predictable results I think is too abstract. I would really specialize to user interface, though it is not the only application possible to statecharts.
maybe something like
A user interface is a reactive system which translates events received by the interface to actions on the interfaced systems.
Statecharts is a visual formalism for complex reactive systems.
Describe your user flow
Get the actions to execute
maybe a three-pronged panel with user in panel 1, user interface in panel 2, interface systems in panel 3, some arrows showing events from the user to the user interface, and from the interfaced systems to the interface, and then a last arrow which represent the action on the interfaced system.
and then the same picture, but replacing the user interface by the statechart. This gets to show that a statechart is a model of the user interface, and a translator between events and actions.
well that is a bit ugly
grr spectrum chat does not accept svg files?