PSA: new tag "ux-surprise" on GitHub

I have added a new label “ux-surprise” on github. This tracks problems that a casual DB/SQL user would be “Surprised” with if they don’t know much about CockroachDB and are working from public information published on the web.

The label should be used for things like discrepancies between our docs and product; discrepancy between our product and other products that we don’t explain/document properly; and corner cases of our functionality that may cause a headache for users to understand properly. It can target both functional problems (“this does not produce the expected outout”) and extra-functional problems (“this is slower than I expected”).

I initially thought about using the name “ux-bug” but I feared that some people would come and say “‘ux-bug’ is too close to ‘bug’, so let’s merge them”. I really think that a ux bug is categorically different from our other product bugs in that a “fix” may in some cases be a matter of improving our docs.

Also as a side effect I predict that the process of addressing “UX surprises” will increase the feeling of users that our product is “polished”.

I like this. Do you see confusion/surprises around the documentation falling into this category as well, or should those go elsewhere? One could argue that documentation is just as relevant to the user experience as the product behavior itself.

For instance, I got tripped up today looking through the functions and operators documentation, asking myself things like:

“how can the < operator be applied to two bools? What’ the expected behavior there?”

as well as:

“What is the 4th string parameter do (and the rest of them, for that matter) in the latter of these functions?”:

regexp_replace(string, string, string) -> string
regexp_replace(string, string, string, string) -> string

(Those are just examples, I don’t actually need answers). Issues like that, while not strictly related to functionality, makes for a confusing user experience nonetheless.

Hi twrobel!

I agree that incomplete docs can also generate a double-take in user experience.
However if you know the issue is with docs specifically we already have a platform for that. In that case we’d prefer you to either

  1. file an issue directly on or
  2. use the feedback button at the bottom of a doc page (the mini-form “was this page helpful?” – with either yes or no you get a chance to place a text comment).
    The ux-surprise label on the product repo is intended more for cases where there is initially some uncertainty about whether the issue is a product bug (needed technical change) or a doc bug (managing user expectation).

Beyond this, to react to the two specific issues:

I hope this helps.

1 Like