@benaryorg @sindarina @miki You don't learn by giving people a hard time. That's been established by quite a long time. It's a bullshit "didactic" theory that's still promoted by authoritarian teachers. I thought we were over that crap.
It's all about making good documentation. And any good technical writer will tell you that things that are written in an accessible and self explanatory way are better than unclear/complex technicalities with explanatory text *around* them.
Take *any* well-written technical paper, document, book. None of them will slap a lot of complicated formulas there and then have a second page explaining them. It will pick you up from line one and guide you through every step. It will have self-explanatory and carefully chosen names and terms for concepts introduced.
And no, 192.0.2.0/24 is not self-explanatory or obvious. Maybe it's simply bad how all this unfolded that the RFC came too late and we should've standardized 1.2.3.0/24 as test IP range, idc. But I do care about things being as obvious as they can (but not more than that).
I follow that RFC, in most cases. But there are cases where I don't, and repeating a lot of points that *I already know* won't change my mind. Addressing the problems I have with that RFC might. But alas, that doesn't happen.
@ljrk neither am I saying to make it hard to get the information from the documentation nor am I saying to strip down the documentation by making it "self explanatory". Something being "self explanatory" is a concept in which I do not believe because rather than making something more accessible it usually just causes different people to have issues with the documentation.
If you remove the "don't forget to change the IP" entirely then you're just tripping up a different set of people.
The only real solution to the problem of making things clear is by employing more than just text in documentation. Be it visuals, or something interactive.
The interactive part (OVH's API docs being an example, you enter values in textboxes and it generates PHP or Python code, would love curl too but still good) is hard to get right and often not really possible (think text documentation).
However the visual part is comparatively ubiquitous.
Or if the command gets a little too long and you should factor out parts anyway:
This doesn't solve everything, but it both conveys the need to change a value as well as it possibly can IMHO (at least better than just hoping that 1.2.3.4 catches someone's eye) and it does make it easy to retrieve this message. Although it is less accessible for users of screen-readers, but for that you'll probably always need some regular text that is just™ readable by a screen reader).
The idea you're describing in your third paragraph, or at least in the way that you describe it, is very much tied to a multi-step thing, an API documentation may not contain multiple steps. Other pieces of documentation may not warrant introducing any concepts, they are just that one thing you should do and the only fluff that could possibly be there is a small info box telling you to change values accordingly. And whenever a technical paper, document, book, or anything of sorts tries to denote that this is an example, then it will probably make it clear that this is, in fact, an example, something that has to be reviewed before using, something that has to be understood before executing, something that is a template to the thing that you are trying to do.
There should never be an IP already filled out in anything that looks copy&pastable unless it is clearly marked as "this is what it looks like for me, your mileage may vary" together with the template of how to find out what you ought to do yourself.
That's where the IP ranges kick in. They aren't there to put in some code to start with, they're there to describe how things should look like in most cases:
The IPs should not serve as placeholders, but as examples themselves IMHO.
Whatever documentation uses them inline without having a clearly established context (that of an example) and clear marking for which parts are variable, I don't like it.
Tech has the same issue whenever Regex comes along and people push all of the verification into the Regex itself (see the dreaded email regex that doesn't ever work anymore). No, the Regex is a means to denote a patterns, which is then captured and actually validated in a second step. Shoving Integer range validation into a Regex is the pinnacle of "you won't be able to maintain this in two weeks", and it's the same with IPs in documentation. Don't embed them. Put them next to the important part as an example. Remember the old placeholders in text inputs on the web? When there was actual text in there that you could just submit if you did not change the field, because it was stored as the value? And then finally came along the browser-supported placeholder attributes that allowed us to specify something that is visible, but not part of the content. This is what documentation needs those IPs to be. A thing to look at, but not to use.
And as someone who has read more network documentation than I'd like, 10.10.10.10 communicating with 11.11.11.11 is just as unusable to me. Call it Host A and Host B, or better even put an example there and have them be Server and Client or something.
Put the IPs there as an example of what it could look like, but do not use it to describe the actual content.
I don't want to know that 10.10.10.10 establishes a connectio— No! The client uses its internal IP (in this case 192.0.2.1) to connect to the servers public facing IP (here 203.0.113.1) which is visible to the server as the routers public facing IP (198.51.100.1) thanks to NAT.
Why anyone would ever keep talking about the IPs is beyond me. So many people have trouble with numbers already, especially if you have more than two of them, they get mixed up, the communication gets tedious, I haven't seen a person who was good at all those numbers in my life.
And in this kind of documentation, does it matter whether the IP is 1.1.1.1 or 198.51.100.1? I would say No, because it is clear in every sentence that these are examples.
@ljrk neither am I saying to make it hard to get the information from the documentation nor am I saying to strip down the documentation by making it "self explanatory". Something being "self explanatory" is a concept in which I do not believe because rather than making something more accessible it usually just causes different people to have issues with the documentation.
If you remove the "don't forget to change the IP" entirely then you're just tripping up a different set of people.