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