Documentation for UI #6722
Documentation for UI #6722
Conversation
There was a problem hiding this comment.
Awesome work on this! I'm super excited to finally have a section in the docs for this. I've registered my usual nit-picks and edits. Biggest need, I think, is a few more images and different composition for some of the images we have.
We are currently thinking about the best way to organize it — whether it should be as you have it here in a top-level section or if it should be elsewhere. We may end up keeping it like this, but I'd love to hear any thoughts you have. I suspect you placed it here so it would be alongside CLI, which makes perfect sense. We've also questioned whether CLI and UI should be under a single top-level category and, if so, what that might be called.
Co-authored-by: Devon Campbell <devon@edgedb.com>
That could make sense. If that ends up being the case then maybe something that grabs eyeballs like "Accessing EdgeDB" or "Accessing your EdgeDB database". Someone encountering EdgeDB for the first time will first gravitate to Get Started, inside which is a link to The CLI but that page only talks about installation and whatnot. Likewise for the CLI menu which is fine but the top-level page there only mentions the REPL as an afterthought. The "Accessing your EdgeDB database" top-level menu could then maybe diverge into the following:
And looking at the "Over HTTP" page I think it deserves some rescuing from the Client Libraries section it's in now, as it can be pretty useful and also has metrics, which is way off in another page here that also deserves to be rescued: https://www.edgedb.com/docs/reference/http |
docs/ui/index.rst
Outdated
| .. code-block:: | ||
|
|
||
| # CLI REPL output | ||
| 'function default::get_url() -> std::str using | ||
| (<std::str>\'https://geohack.toolforge.org/geohack.php?params=\');'} | ||
|
|
||
| # UI REPL output | ||
| function default::get_url() -> std::str { | ||
| volatility := 'Immutable'; | ||
| using (<std::str>'https://geohack.toolforge.org/geohack.php?params='); | ||
| } |
There was a problem hiding this comment.
Could you update this example to mirror the one above, with two distinct code blocks and showing the query?
| .. image:: images/data_explorer.png | ||
| :alt: The data explorer page in the EdgeDB UI. The icon is three bars | ||
| stacked on top of each other: blue, purple, and orange. A sample | ||
| query via the Data Explorer shows information about a user-defined | ||
| object type called a Booking. | ||
| :width: 100% | ||
|
|
There was a problem hiding this comment.
I think I would favor putting these images before we describe the UI rather than after. I know we show the REPL example after, but the difference for me is that's an example to demonstrate what we've told you whereas these are the actual UIs we're describing. I would put this image up on line 39 so that the user can have a look before we start talking about it. I think that also makes it clearer which image is associated with which description.
There was a problem hiding this comment.
Maybe it's the copywriter in me that generally opts for a short description followed by an image. Generally you go Product feature -> short blurb on what it's good for -> image to seal the deal. e.g. https://www.samsung.com/us/watches/galaxy-watch6/
I guess it depends on whether to generate any excitement (ooh, what does this feature look like? Ah, there's a picture) vs. more documentary feel (here's so-and-so feature, now let me tell you a bit about what you just saw)
Interesting to think about the slight difference in feel. Can definitely move the images before the description of course as it's quite a subtle difference.
docs/ui/schema_viewer.rst
Outdated
| .. code-block:: | ||
|
|
||
| abstract constraint std::max_value(max: anytype) { | ||
| using ((__subject__ <= max)); | ||
| } errmessage := | ||
| 'Maximum allowed value for {__subject__} is {max}.'; | ||
| annotation std::description := | ||
| 'Specifies the maximum value for the subject.'; | ||
| ; | ||
|
|
||
| abstract constraint std::max_ex_value(max: anytype) { | ||
| using ((__subject__ < max)); | ||
| } errmessage := | ||
| '{__subject__} must be less than {max}.'; | ||
| annotation std::description := | ||
| 'Specifies the maximum value (as an open interval) for the subject.'; | ||
| ; | ||
|
|
||
| abstract constraint std::max_len_value(max: std::int64) | ||
| on (std::len(<std::str>__subject__)) { | ||
| using ((__subject__ <= max)); | ||
| } errmessage := | ||
| '{__subject__} must be no longer than {max} characters.'; | ||
| annotation std::description := | ||
| 'Specifies the maximum length of subject string representation.'; | ||
| ; | ||
|
|
||
| .. image:: images/stdlib_search.png | ||
| :alt: A search result from the Schema Viewer page in the EdgeDB UI, | ||
| in which a search for the keywords max and val has turned up | ||
| three matching functions: max value, max ex value, and max | ||
| len value. | ||
| :width: 100% |
There was a problem hiding this comment.
I like the addition of the image, but it feels a bit redundant to have the text output and then an image of the same text output. Maybe we ditch the text but flesh out the image alt a bit?
There was a problem hiding this comment.
Sure, have done that. Without making the alt text too long, I guess the most important point to add is that the search doesn't just show the function names but also their declarations which lets you see the internals and know exactly what the function behaviour will be.
for consistency across docs
to more explicitly reflect contents of this view
to be less ambiguous
to disambiguate with "Instance dashboard"
where we are not quoting the names of other UI labels
to avoid any ambiguity between the CLI REPL and the UI REPL when a user is looking at this page
Links by label name don't seem to work across repos
This follows the CLI documentation layout in having one page per relevant portion, but adds a touch of friendlier tone since the UI is far more likely to be used by new users or those without a technical background.