I had some notes about the Tour to Dgraph, regarding cosmetic changes:
-
A spacing issue, as pictured in the screenshot below, occupies nearly half the screen:
-
I think tours should be designed to fit on one page, without any need for scrolling. To go through the tour, one has to scroll down every time they change the page, which is not good UX. For example, see A Tour of Go. They have a small font, minimal layout, and have broken the content into tiny chunks - the result being that one doesn’t have to keep scrolling to take in the content (at least on my system).
-
Even if a scrollbar cannot be avoided, it should be added to the two individual components displaying the explanation and the code, so that the bottom panel with page numbers is always visible. The whole page should not be scrollable, in my opinion.
I also felt that it could be much better with some structural changes too:
-
The Tour should not require a local instance. While it does make queries interactive, there is no way of just seeing what the result is without spinning up a local instance and loading data (which means going through the entire intro). This can put off users who just want to see what Dgraph is all about before getting their hands dirty, as well as users who are simply revisiting a single page of the tour.
-
Language tags have a pretty alien syntax at first, and are used in the Tour without proper introduction. When they are used to load the schema, we are told to ignore the syntax, as it will be explained later. Then, in Basic Features, page 1, we make a query using
name@.- at this point, the user has no idea what that means! Then on page 2, we usenamein one place andname@.in another. I think the use of@.should be avoided altogether until it has been explained. -
There are pages where we can’t help the user with the query. Even if we can’t get the UID, we should at least have a Show Answer for users who don’t want to / are unable to construct a query to find the UID themselves.
-
On the same page,
...michael...in the query field is invalid GraphQL± syntax, and can cause confusion to someone scanning through. A better way would be to add the hint in a comment. -
The Tour should end with a page congratulating the user and telling them about next steps.
While some of these points may seem like nitpicking, I did feel like the Tour could be much better with simpler language and a changed structure. Tours are really great for people who are on the fence about using Dgraph, and the simpler we make it, the more users will be inclined to dive in. On that note, I think GraphQL/Slash, too, deserve a Tour!