Email or username:

Password:

Forgot your password?
Top-level
lj·rk

@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.

4 comments
Katze replied to lj·rk

@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.

curl https://192.0.2.1/foo
^^^^^^^^^
change this

Or if the command gets a little too long and you should factor out parts anyway:

ip=192.0.2.1 # change this
curl "https://${ip?}/foo"

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:

To do the thing you can run this command:

curl https://$IP/foo

Note that you need to replace the `$IP` with your own IP ([insert pointer on where to find this information here, maybe an inline reference?]), for IPv4 this is just the regular IP as in `192.0.2.0`, for IPv6 bracketed notation is required: `[2001:db8::1234]`.

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.

lj·rk replied to Katze

@benaryorg

> 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.

@benaryorg

> 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.

Katze replied to lj·rk

@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.
Most people I know and have known are from a non-academic background and the majority of thes still tries to cut through docs but ultimately reads the important bits. It's more a habit of trying to skip chapters than parts of a sentence. And skipping in introduction may be much less problematic than skipping the half of the sentence that digs into the actual matter.

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.

lj·rk replied to Katze

@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).

Go Up