json-ld
Playground UI is confusing (New Context)
The "New Context" UI on the playground is confusing. It's unclear to people what its purpose is -- especially to newcomers. The initial UI on the playground should probably just have a simple "JSON-LD validator UI". Maybe some directions could be given there to ask the user if they'd like to see how their JSON-LD looks when it's expanded (directing them to the expansion tab). If we could cleanly get more links to areas in the spec that explain what each tab means, etc. that would be helpful.
There should be some other UI element (tab/button/etc) that can be triggered to go into a "transform" mode/screen. That would make it more clear that you can use the playground to transform your JSON-LD input from one context (or none) to another. We could also have something that's a bit more directed for "adding context" to existing JSON (so JSON input box + the context to add = the result). Something that better explains, visually and interactively, what's going on with JSON-LD and what it brings to the table.
cc: @bollwyvl
I have been thinking about exactly the same things.. I think the easiest quick-fix would be to move the expansion tab to the left and expand it by default (instead of compacting by default). Expansion works more or less like validation. You see how the document is interpreted and it triggers error messages if it can't be interpreted.
A small (i) symbol on each tab with a tooltip that, when clicked, brings you to the spec would also be helpful. So on the expansion tab, the tooltip would say “apply all referenced and embedded contexts to make the data self-contained” or something similar and when you click on it will open the section explaining expansion in the API spec in a new tab.
The "first use" experience is indeed still a challenge. I have been asked by colleagues what the best way to start working with this technology is, and the playground is still not that.
Better inline doc, ideally pulled from the actual spec without leaving the page, would be good, as specs can be scary.
To start with, some iconography for compact, expand, flatten, and frame, would be good. Then visually represent, at least:
- the input
- an option context
- the operation
- the output
There's the concept of a pipeline, a la NoFlo, that a full authoring environment might allow, but that's probably out of scope of what this tool should do. However, it could be that the "subway map" view could be useful for seeing the relationships between the different inputs and outputs.
Regarding your second point, about interactivity, one of the key questions is probably:
For my current caret/cursor position, what tokens in other views would be impacted if I changed this? What tokens, if changed, would impact this one?
I can imagine a really ghetto way to do the first part using diffs: . There wouldn't be an easy way to tell, when hovering over some output, what part of the input(s) yielded it... since jsonld.js doesn't interact with strings directly, I don't know the right way to instrument this (meta)data.
I'll see if I can do some work on this, as the southeast USA is going to be closed again.
I recently came upon these two sites for sweet.js:
- http://jlongster.com/Writing-Your-First-Sweet.js-Macro
- http://sweetjs.org/browser/editor.html
So perhaps there is a narrative document for introducing the concepts for the "first use", and then a much more austere version of the playground that is more aware of full-screen real estate.
what I liked about the tutorial:
- the tone is light
- the "stepper" for watching the algorithm work
what I liked about the editor:
- already ready to be full-screen
- though kind of weird at first, the constantly updating the URL is actually nice, as it makes better use of the browser UI rather than forcing you to learn something new