[cmovq]

> 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.

[Tobani]

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.

[superfrank]

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.

[yencabulator]

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

[redhale]

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.

[tedunangst]

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.