Be careful of the examples you use. They stick
blog.thinkst.com
Be careful of the examples you use. They stick
1–10 of 129 posts
Re: Be careful of the examples you use. They stick
#2The 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.
Re: Be careful of the examples you use. They stick
#3The 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.
Heh. "You can totally put in any value here, as long as its exactly this one"
Re: Be careful of the examples you use. They stick
#4The 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.
Heh. "You can totally put in any value here, as long as its exactly this one"
"You can have any color car you want. As long as it's black."
-- Henry Ford
Re: Be careful of the examples you use. They stick
#5Oh, absolutely. If you give people an example (and you should), the overwhelming majority will copy the example exactly and then only change what they are forced to change when it doesn’t work otherwise. Therefore, prepare your examples accordingly.
Re: Be careful of the examples you use. They stick
#6Earlier quoted context omitted.
Heh. "You can totally put in any value here, as long as its exactly this one"
"You can have any color car you want. As long as it's black." -- Henry Ford
Completely off topic aside but I read somewhere recently that the reason for this was that black paint dried much faster than any other colour, which meant less time taking up space in the drying room, which meant more production capacity.
So basically it was black because that kept production costs down.
Re: Be careful of the examples you use. They stick
#7The 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.
Can't think of any examples now though I'm afraid.
Dodged a meta-bullet there...
Re: Be careful of the examples you use. They stick
#8An 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
#9I'm thinking if invalid characters in the examples given would be an acceptable solution.
For DNS records this could be XML-like tags like ..
On one hand, it prevents blind copy-pasting but on the other hand, your example is invalid.
Re: Be careful of the examples you use. They stick
#10An 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 still moving from no-logic (static) to somewhere-logic.