Allow commenting in Spec


I tried to create a spec for something I am currently working on. I immediately missed the possibility to comment in a spec. I just have some states and cannot communicate anything more than states and actions. I cannot say for example in a typeahead what objects the typeahead should suggest, or if there are permission restrictions, what those are.

So it would become immediately more useful, if I could add a comments somehow using a # or // syntax.


Ah I just realized, that commenting is actually allowed with #

But I would like to see the comments in the diagramm. Somethign like:


Hi @RolandStuder,

Thanks for writing!
Right now comments are associated with the items directly underneath them, and they’ll show up as tooltips if you hover over the state/transition.

We thought this would be a nice way to make the accessible in the diagram without cluttering the diagram with potentially paragraphs of text.
I doubt it’s optimal, though — the way the diagram works is something @ryan and I want to revisit once we see what sort of sketches people are making.

For now, though, we’re focusing on writing more tutorials and videos to teach people the core ideas, so it might be a while before we start seriously tweaking the editor and diagram.


Hey @kevin, I second any approach to avoid clutter. A visual/actual indicator could also be more appropriate. For instance, a question mark in a circle (?) or a low opacity hash (#) next to the lines with comments. It might also be ARIA friendly.


Hi @julio73, sorry, I’m not following — by “next to lines with comments” do you mean adding something to the states in the diagram view? Or adding something to the spec text editor?

If by ARIA you are referring to accessibility — it’s not something we’ve addressed yet.
I suspect the spec and prototype areas might be hard to “escape” from using just a keyboard, and the event links in the diagram aren’t tab-able at all.
I’ll take a pass with a screen reader later this week and see if we can make the app usable without a mouse.


Hi @RolandStuder and @julio73,

We’ve added little indicators to states in the diagram when they’re associated with comments.
Holding the mouse over these indicators shows the comment as a tooltip:


We think this makes it easier to read the comments while interacting with the diagram, while keeping the diagram concise.
Let us know what you think!


Some feedback here.

First—really helpful to add comments!

Second—it was very counterintuitive to me that the comments belong the item below it. Given the hierarchical nature of the spec, I’d expect everything below and indented to belong to the item above.

Hope this helps!


I concur on @timdose second point. I would also suggest allowing single line commenting on the same line as the item being described. eg:

NSFW # Neglected to Save File in Word