Suppose you get a phone call. One of your users - Alice - has hit a snag, so she calls you to report it. You dutifully open Zoom, watch her demonstrate, take notes, and file an issue in Gitlab.
Alice called at 3pm today. She's enabled the Gizmo component, but now she has a problem editing widgets. I watched this process on Zoom: 1. Search for gizmos. 2. Click on the third gizmo record (#79) 3. Open the widget tab 4. Click on the last widget #116 Note that it only crashes on widget #116. The other widgets on that screen are fine (eg #92 and #95 are ok). There's something weird about widget #116.
Of course, you made Rookie Mistake #1 (which is to mix-up references like “#1”). This creates a bunch of cross-references for unrelated issues:
This is not a big problem. It’s well-known behavior. Markdown has an easy fix – when you want to show exact text, use backticks. It works for all kinds of characters, including
Alice called at 3pm today. She's enabled the Gizmo component, but now she has a problem editing widgets. I watched this process on Zoom: 1. Search for gizmos. 2. Click on the third gizmo record (`#79`) 3. Open the widget tab 4. Click on widget `#116` Note that it only crashes on widget `#116`. The other widgets on that screen are fine (eg `#92` and `#95` are ok). There's something weird about widget `#116`.
#3 – that’s fine. Try it on Gitlab, Github, Mattermost, mkdocs – they all work as expected. Except… in Gitlab… some of the numbers get a mysterious black box:
My first reaction was: “Uhoh, there’s a font problem.” But I figured it wasn’t critical, it would take too long to investigate, and it would probably go away (either with a future cache-flush or future upgrade). But… it’s been a couple years… and it still happens. And today I felt like a goof (I wrote a comment with several confusing boxes - and didn’t know the cause).
Turns out… it’s not a font bug! It’s a feature called a “Color Chip”:
That sounds pretty neat… if you’re a web-designer, who’s day-to-day discussions involve color choices like
#dadaff. (Those are cool colors… too bad you can’t see them… because the forum lacks Color Chip support…) I can totally imagine how the feature would augment design conversations.
But if you stumble into it accidentally, you might feel more
#911 about black boxes which randomly insert themselves.
Anyway, I find it confusing.
I have some suggestions, and I don’t know whether to call these “bugs” or “features”. So instead I offer this forum-brain-dump:
- Tighten up the parsing. Only activate if there are six hex digits. This should reduce accidental activations. (FWIW, I checked Github – they require all six digits.)
Make the color chip more obvious. If the user hovers/clicks on a chip, then give some feedback. Show a tooltip. Say it loud: “This is a color! This is
#991111! This is
rgb(153,17,17)!” Include a big swatch. Let the user fully soak-in the amazingness of that specific shade of red.