Be careful of the examples you use. They stick • Hacker News Board

Re: Be careful of the examples you use. They stick

#11

Post by l0b0 » Mon, Aug 21, 2023, 10:36 AM UTC

This is also an opportunity to think about the value of a piece of configuration. If an example configuration value works for 40% of users without modification, should that value even exist? Think Bash's `HISTCONTROL=erasedups`, which shouldn't be necessary to set in the 21st century. Or should it be auto-generated, like Docker's container names?

In the very best case, the defaults are so good that an empty configuration does what most people want. Think ripgrep, …, welp, I can't really think of many good examples. Browsers need extensions, Bash needs a decent prompt, even many pro cameras need to be configured to save raw images by default.

Re: Be careful of the examples you use. They stick

#12

Post by personjerry » Mon, Aug 21, 2023, 10:39 AM UTC

Why is "use more examples" the solution? If the users are copy pasting the code, why not just generate random strings thereby showing an example and also fulfilling their own requirement of non-identifiable strings?

Re: Be careful of the examples you use. They stick

#13

Post by tough » Mon, Aug 21, 2023, 10:46 AM UTC

nicexe wrote: post #10

PeterisP wrote: post #8

An interesting thought is that the examples in your documentation don't necessarily need to be static and the same for everyone. For example, if a user is logged in, you can autofill the appropriate accounts/domains/ids/etc to make the example work out of the box; and if some ID needs to be essentially random, then you can make it actually random when you generate the example.

They don't have to be static but making them dynamic might not worth the cost. From a simple static page, now you need an API service, most probably connected to a DB or somehow integrated to the rest of your backend. So markdown suddenly isn't enough and you need some server-side logic. For random strings, you can do this with client-side logic, which in some cases might be easier than server-side logic. But you are…

SwaggerUI/OpenAPI support this to add your own users API credentials to the api call examples, if you care to implement.

as a develoer, is just a nice touch that I can copy paste an example of code snippet and since I'm logged in they can give it to me already with a valid api key.

ymmv

They also allow to output examples in as many langugages/sdk's as you need too

Re: Be careful of the examples you use. They stick

#14

Post by kzrdude » Mon, Aug 21, 2023, 11:01 AM UTC

l0b0 wrote: post #11

This is also an opportunity to think about the value of a piece of configuration. If an example configuration value works for 40% of users without modification, should that value even exist? Think Bash's `HISTCONTROL=erasedups`, which shouldn't be necessary to set in the 21st century. Or should it be auto-generated, like Docker's container names? In the very best case, the defaults are so good that an empty configura…

How do we combine evolution and development with backwards compatiblity? I think it's quite natural that we end up with this conundrum. Like say for example Vim having outdated defaults, because changing them could disrupt existing users. A reboot/fork of it can reset and start fresh but will eventually in its own development hit the same problem.

Are there examples of projects who solve this well?

Ripgrep's author is also very careful about breaking changes - I think that means it will also one day have outdated defaults!

Re: Be careful of the examples you use. They stick

#15

Post by nicolaslem » Mon, Aug 21, 2023, 11:02 AM UTC

tough wrote: post #13

nicexe wrote: post #10

Earlier quoted context omitted.

They don't have to be static but making them dynamic might not worth the cost. From a simple static page, now you need an API service, most probably connected to a DB or somehow integrated to the rest of your backend. So markdown suddenly isn't enough and you need some server-side logic. For random strings, you can do this with client-side logic, which in some cases might be easier than server-side logic. But you are…

SwaggerUI/OpenAPI support this to add your own users API credentials to the api call examples, if you care to implement. as a develoer, is just a nice touch that I can copy paste an example of code snippet and since I'm logged in they can give it to me already with a valid api key. ymmv They also allow to output examples in as many langugages/sdk's as you need too

This unfortunately encourages users to hard-code secrets since the example snippet they get literally does it.

Re: Be careful of the examples you use. They stick

#16

Post by hardware2win » Mon, Aug 21, 2023, 11:10 AM UTC

How about generating randomish suggestion like

company-35642.domain.com

Re: Be careful of the examples you use. They stick

#17

Post by gray_-_wolf » Mon, Aug 21, 2023, 11:29 AM UTC

l0b0 wrote: post #11

This is also an opportunity to think about the value of a piece of configuration. If an example configuration value works for 40% of users without modification, should that value even exist? Think Bash's `HISTCONTROL=erasedups`, which shouldn't be necessary to set in the 21st century. Or should it be auto-generated, like Docker's container names? In the very best case, the defaults are so good that an empty configura…

> Think Bash's `HISTCONTROL=erasedups`, which shouldn't be necessary to set in the 21st century

As in that it should be the default? Or only option? I personally do not have (and want to have) that set, and I am hardly alone. Any change in defaults fucks someone over, especially in things like bash, where you ssh into many machines with many different versions of bash...

Re: Be careful of the examples you use. They stick

#18

Post by tetrep » Mon, Aug 21, 2023, 11:32 AM UTC

alex-moon wrote: post #2

The opposite is also true. It happens rarely, but I have been bitten by trying to configure something to be what I would like it to be, only to discover it had to be what was in the documentation for it to work, generally with nothing in the documentation itself to clarify. Can't think of any examples now though I'm afraid.

I don't think that's in opposition to the posted article, it's just a lack of documentation ("with nothing in the documentation itself to clarify").

Re: Be careful of the examples you use. They stick

#19

Post by saurik » Mon, Aug 21, 2023, 11:46 AM UTC

gray_-_wolf wrote: post #17

l0b0 wrote: post #11

This is also an opportunity to think about the value of a piece of configuration. If an example configuration value works for 40% of users without modification, should that value even exist? Think Bash's `HISTCONTROL=erasedups`, which shouldn't be necessary to set in the 21st century. Or should it be auto-generated, like Docker's container names? In the very best case, the defaults are so good that an empty configura…

> Think Bash's `HISTCONTROL=erasedups`, which shouldn't be necessary to set in the 21st century As in that it should be the default? Or only option? I personally do not have (and want to have) that set, and I am hardly alone. Any change in defaults fucks someone over, especially in things like bash, where you ssh into many machines with many different versions of bash...

Omg, I just read the documentation for erasedups and I'm actually shocked anyone would want that feature turned on, to the point where it never even would have occurred to me to implement it in the first place and if the feature worked like that without some way to turn it off I'd have been super angry :(. Maybe we are parsing that sentence wrong and by "shouldn't be necessary to set" the idea is "it is useful in situations where you have limited disk space / memory but in the 21st century no one would need to set this so it might as well no longer be supported"?

Re: Be careful of the examples you use. They stick

#20

Post by Karellen » Mon, Aug 21, 2023, 11:53 AM UTC

kzrdude wrote: post #14

l0b0 wrote: post #11

This is also an opportunity to think about the value of a piece of configuration. If an example configuration value works for 40% of users without modification, should that value even exist? Think Bash's `HISTCONTROL=erasedups`, which shouldn't be necessary to set in the 21st century. Or should it be auto-generated, like Docker's container names? In the very best case, the defaults are so good that an empty configura…

How do we combine evolution and development with backwards compatiblity? I think it's quite natural that we end up with this conundrum. Like say for example Vim having outdated defaults, because changing them could disrupt existing users. A reboot/fork of it can reset and start fresh but will eventually in its own development hit the same problem. Are there examples of projects who solve this well? Ripgrep's author i…

A reasonable compromise would be to allow changing defaults whenever there's a major version bump.

ripgrep seems to have a major version bump every 18 months or so, which seems a bit excessive. OTOH vim went through 9 versions in 30-something years which seems more reasonable. Although I think there was more churn early on. ISTR vim 6 being around for a long time.