News for hackers. Stuff that matters.
Re:Be careful of the examples you use. They stick by PeterisP on Monday August 21, 2023 @05:43AM (#37207258)
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.

Re:Be careful of the examples you use. They stick by nicexe on Monday August 21, 2023 @05:56AM (#37207333)
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 still moving from no-logic (static) to somewhere-logic.

Re:Be careful of the examples you use. They stick by tough on Monday August 21, 2023 @06:46AM (#37207689)
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 by nicolaslem on Monday August 21, 2023 @07:02AM (#37207847)
This unfortunately encourages users to hard-code secrets since the example snippet they get literally does it.