@ljrk @sindarina @miki In documentation of all places you do have the ability to actually write that this value needs to be changed though.
"Important: insert the IP address of [whatever] here"
Top-level
@ljrk @sindarina @miki In documentation of all places you do have the ability to actually write that this value needs to be changed though. "Important: insert the IP address of [whatever] here" 8 comments
@ljrk @sindarina @miki Let me rephrase this in financial terms, maybe then I'll get across how important it is to not have random IP addresses somewhere in code, docs, or even blog posts. Currently the entire 1.2.3/24 is unassigned as far as I can tell, probably because people used those addresses at large, and simply announcing the /24 (and you have to announce an entire /24 at a time, smaller routes won't be accepted on the internet) will probably net you an enormous amount of traffic. The APNIC Debogon Project for instance has the goal of reintroducing such problematic network addresses back into the internet by working with a variety of ISPs and other instances to remove something like old filter lists for networks that were once widely blocked. The filter lists probably aren't too much of a problem in this case, it's more a matter of the amount of bogus traffic you'd get if you announced that network, and considering it's stemming from IPs present in various documentation, maybe even defaults somewhere, it seems rather likely to me that the reintroduction of that network probably won't happen anytime soon (although some people would probably pay very well for that IP). So let's get into the fun part; IPv4 address space is expensive. Very expensive actually. Some sources estimate around 50$-70$ per IP, and /24 blocks do seem to net one around 10k$. I'm not too involved in the financial part of networking so I'm not too sure how reliable these numbers are, but sources seem to be somewhat consistent in those numbers. Also last time I heard about this kind of thing companies would try to buy existing but failing other companies to acquire their allocations rather than buy them to avoid having to go through a bunch of reassignment and justification stuff. Even better would be adding IP addresses from networks which have actual technical implications like multicast ranges or other reserved networks which could potentially¹ cause actual issues rather than just not working. Then there's the part about potential security implications; you add 1.2.3.4 to your docs for a curl command that uploads some data, expecting people to input the correct address, but some people still just copy&paste it. Years later maybe. Maybe after the IP has been reassigned and maybe there is a webserver running on that IP now. And they just inadvertently uploaded some important, maybe even PII, data to that server, which may be on a different continent.… ohhh boi, don't we all love to get an email from a service provider to tell us they accidentally leaked some information. I know that writing documentation is hard. So hard in fact there are people who specialize in doing this; technical writers. But embedding IPs, domains, or other internet resources you do not own to your documentation creates problems for someone, somewhere. Things like these may seem like a good idea if you can ignore the consequences, but we all know you shouldn't ignore the consequences just because you're not affected by them. @ljrk @sindarina @miki Let me rephrase this in financial terms, maybe then I'll get across how important it is to not have random IP addresses somewhere in code, docs, or even blog posts. Currently the entire 1.2.3/24 is unassigned as far as I can tell, probably because people used those addresses at large, and simply announcing the /24 (and you have to announce an entire /24 at a time, smaller routes won't be accepted on the internet) will probably net you an enormous amount of traffic. The APNIC... @ljrk @sindarina @miki Personal opinion: if you're writing documentation in the assumption that people won't read half of it then I have a personal issue with your way of doing, because I would much rather you stop reinforcing that existing bias. The fallout of any form of text or information base trying to safeguard the people who won't even stop to read a single info box or bold written text is that people suddenly read news headlines and consider the entire article read. Or to read the first three words of a sentence and assuming they know the rest. This causes issues in all areas of life; prime example being the misinformation bias surrounding news because people don't bother to read more than the headline. Making it easier to get away with not reading the important bits is part of the problem IMHO, not a solution. Not by a long shot. @ljrk @sindarina @miki Personal opinion: if you're writing documentation in the assumption that people won't read half of it then I have a personal issue with your way of doing, because I would much rather you stop reinforcing that existing bias. The fallout of any form of text or information base trying to safeguard the people who won't even stop to read a single info box or bold written text is that people suddenly read news headlines and consider the entire article read. Or to read the first three... @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. @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. @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. 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. 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.
The IPs should not serve as placeholders, but as examples themselves IMHO. 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. 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. Didn't say that. I said that it should ideally be made as clear as possible from the command itself, you yourself give many of such examples. But it's friggin' hard and I had people literally run commands with placeholders 1:1 despite everything you described. And not too few. Maybe I'm burnt because I taught freshmen CompSci, most of them having never opened the command line a week before. But I always try to assume the least competent user – which means, assume that they do not *know* that RFC and they do not look at surrounding hints. > If you remove the "don't forget to change the IP" entirely then you're just tripping up a different set of people. Didn't say that. I said that it should ideally be made as clear as possible from the command itself, you yourself give many of such examples. But it's friggin' hard and I had people literally run commands with placeholders 1:1 despite everything you described. And not too few. @ljrk I think the freshmen CompSci may be the reason indeed. Considering that school, university, most sorts of academics in general will encourage or even require skimming texts. When people from that background arrive in tech and see actual good documentation it's probably the firnt time they read a text that's written to be read for information, not written to comply with academic standards. I get that we shouldn't make participation hard for people, but in that one instance I think it's arguably okay to do something to get that (IMHO toxic) mindset out of their heads. However overall I still don't think some inadvertent issue like making networks unusable or breaking your local connectivity by accident (something detecting public IPs and disabling a port or whatever) is worth the (presumably small) margin of people who will notice the funky looking address. But at this point I'd have to agree, I am repeating myself, so I won't reiterate :blobCat_wink_tongue_out: @ljrk I think the freshmen CompSci may be the reason indeed. Considering that school, university, most sorts of academics in general will encourage or even require skimming texts. When people from that background arrive in tech and see actual good documentation it's probably the firnt time they read a text that's written to be read for information, not written to comply with academic standards. @benaryorg That's why I wouldn't put 1.2.3.4 in docs/example configs for... idk, a BGP router or something lol. As I said, it really comes down to the target group, and if I get more confusing/questions about 192.0.2.0/24 and it holds up students or confuses them, I tend to use 1.2.3.4 (it's mostly oral lectures, although I hate giving lectures). |
@benaryorg @sindarina @miki Yep, and observe how people ignore it. Anyone who believes that documentation is actually read is naïve.
Everything that can be "self-documenting", i.e., *self explanatory* and obvious should be made/written like that. Any "surrounding" documentation is less likely to be read.