Comment by superfrank | Hacker News Reader

Comment by superfrank | Hacker News Reader

> It’s important to realise this isn’t a customer-side issue; they shouldn’t have to consider the impact of every configuration option we choose to put in front of them. They don’t have the full context and knowledge, and expecting them to be experts in the nitty gritty of Canarytoken discoverability

Yes!

> Going forward, we will show multiple examples of prefixes. A user looking to add a custom domain will see a variety of example zones when they visit the page, and the examples will cycle each time they open the configuration page. We want to convey that they have options in choosing the name, and we show them a variety of sample options. Our hope is that this will prompt customers to pick their own names, and if they do rely on our examples then those are now spread over a large list of examples.

No! They were so close and yet it sounds like they've still missed the point. The issue is that users don't understand the "why" behind the prefix. Just randomizing the prefix that they're shown does nothing to change that.

IMO, a better solution would be. 1. The shortest possible explanation under the field of why you shouldn't use "someprefix". 2. Prevent users from using "someprefix" as the prefix and show them the warning again. By eliminating the default option as an option, you force your users to leave auto-pilot mode and actually consider their choice.

> 2. Prevent users from using "someprefix" as the prefix and show them the warning again.

Don't do this - examples in documentation should be valid. Having an example that doesn't work when the user tries it out will just lead to frustration.

I ran a blogging SaaS platform for a while. I had some instructions for configuring a reverse proxy to serve the blog. There were instructions for most major web servers. One step was adding a custom header.

- Go to <link> and get your publisher ID - Add the following line to your config(replacing xxx-xxxx-xxxxx with your code from the previous step):

AddHeader X-Publisher-Id: xxxx-xxxxx-xxxxx;

We had a bunch of people leave the x's in and were confused why it wasn't working. So we made a blog that explained the misconfiguration, and replaced xxxx-xxxx-xxxxx in the documentations with that blog's ID. We got far fewer support requests after that.

I strongly disagree.

First, I've come across plenty of documentation that has commands that you can't just copy paste into your terminal. As long as the parts a user needs to fill in are clearly marked and explained, I don't see an issue. Especially in a case like this where there isn't a clear "right" answer and what works for one user may not make sense for another.

Second, I feel like there should be some sibling of Hyrum's Law (https://www.hyrumslaw.com/) that says that users will eventually do everything you tell them not to do.

If you don't want users to do something, then you need to protect them from themselves and explicitly prevent it. Just saying "don't do this" and expecting users to listen isn't going to work.

This gets fun when the example is something like instructions for wiping your disk to install a new OS. If you use an invalid disk name, they get errors. If you use a valid disk name, they wipe the disk on the wrong computer.

There are plenty of scenarios where that is not desirable. Perhaps most famous is IP addresses: https://www.rfc-editor.org/rfc/rfc5737.html

Disagree. Think of any example that includes the configuration of a secret like an API key. Typically you see something like "<API key>" or "xxx-your-api-key-xxx" that signals to the user that they need to input a real value rather than leaving the default, usually coupled with a nearby note describing how/where to get said key.

The example here is of course slightly different, but I think a similar pattern could be applied.

> Prevent users from using "someprefix" as the prefix and show them the warning again.

Yes. That's why https://example.com exists.

Reply on news.ycombinator.com