This reminds me of soda/beer can designs. You know the hole in the ring tab? I used to believe it was there only for it to provide better grip for your finger when opening it. Turned out it was also there so you can fit a straw and have a way of stabilizing it.
Most people had no idea about that.
You’ve mistaken the manufacturers aluminum cost cutting measure for a feature.
I’m not sure that’s their intended design. Old pull-tab cans actually had a ring for you to pull them off (similar to “easy open” soup cans of today)
I’d imagine that as the tab shrunk and changed from pull to a lever action, the “ring” was left as a vestigial design (as a form of skeuomorphism)
Also, the one with the hole requires less material for the same lever width.
Yeah I remember those. Where I grew up that style of ring pull was the dominant style.
One reason why that style was retired in many places was to reduce waste. When you had a ring pull tab that peeled off, most people threw that away separately. I remember seeing those tabs being thrown all over the place.
Look, computers are like idiot savants - incredibly fast and capable of doing all sorts of things with mindless determination, but without a shred of common sense - so when you’re programming you have to literally explain everything including what for you is obvious and there is a whole class of bugs (around corner cases and boundary conditions) related to the programmers not explaining absolutelly everything and forgetting some really rare or unusual situations.
For documentation purposes one should assume that at least some users are like computers, without the savant part.
I write mine with a simple mindset: “imagine we go outside with a net, catch a random person off the street, sit them at the PC and tell them to do X. Will they manage, following this documentation?”
I also number every step (even if they’re stupidly simple and could technically be jumbled into a single sentence), so that when a user calls me asking for help with something documented, all I need to do is ask them “at which step of the instructions are you encountering the problem”, and then they hang up because they never read the instructions in the first place. Saves a lot of hassle!
I have never put it into words like that, more like “make zero assumptions”.
I suppose that being overly thorough can make documentation prone to becoming tedious (unless cares is taken to not talk down to the reader) or too tightly coupled (incurring the need to be updated more often as details of the process change).
How do you usually deal with that aspect? What I do is to make the documentation easily skimmable (for advanced readers) and just accept the need for rework.
How do you usually deal with that aspect? What I do is to make the documentation easily skimmable (for advanced readers) and just accept the need for rework.
Confluence’s “Expand” element. Make everything into an easy to read task-list, but if more details are necessary, just expand a step and get an “idiot proof” description. Bookstack allows that as well, even better, because you can nest them (Confluence had that up until they “updated” the editor and killed half the features).
EDIT: “Include Page” in Confluence also works wonders here. For example, I have an article describing how to RDP to our AD server. In all articles that describe a process that needs to be done on the AD server, I just include that page. If any connection details change, I just edit the original article and the changes immediately propagate to all the other instances.
I really like the social engineering element of your documentation strategy!
You’re brutal. You’re not wrong tho.
The worst is making it about intelligence. Most of the time, the stuff that is “obvious” is not so obvious to most people. Being an arrogant fool about it only makes things worse.
I agree with it not being about intelligence but laziness definitely makes this an issue even with docs
It is a common sense feature.
You got to keep the tea bag higher than the water so that the string is up straight for the capillary action to take place, so that the water goes up to the teabag and fetches the tea back into the mug.
Every application kind of needs two modes: a default mode where the user is railroaded into making the right decision, and an “I’m not an idiot and will actually read the documentation before/after trying to make things work” mode. If you stick the toggle for the two modes somewhere that you’d only find by reading the documentation, people will automatically categorize themselves into the mode the ought to be in.
You actually need proper documentation, though. I’ve had to read source code to discover or figure out how to use cli flags way too many damn times. (I’m not a real programmer, I just work on infrastructure).
I’m sorry to tell you this but you are a real programmer.
Fuck
Oh yes you are a programmer!
I guess I shouldn’t have switched from CS to IT when we got to recursion (I can read it, but I can’t write it to save my life)
Thats totally fine for someone learning. Some really good coders i know still cannot explain complicated data structs or complicated topics. Nobody can “measure” you as a “real programmer” anymore, try as they might to replace us with LLM AI. You wrote code? You’ve been thru it? You’ve learned a good amount? You’re a programmer.
android does it well, if you want “developer” mode that let’s you have better control over your system you have to do some funny IT rituals you can only access by 1. knowing they exist 2. googling how to do it
Steam OS has kind of the same philosophy too. Normal users can treat it like a switch, only ever downloading from steam, and have a perfectly intuitive experience. But power users still have the options to run other software, customize the os, and even outright replace the os.
I love my Steam deck for this reason. I started out using it to replace my switch and now I’m easing my way into learning Linux.
Although it’s pretty easy to stumble upon some guide that you don’t understand that gets you to enable dev mode. Not saying it happens a lot, but there’s not a very high bar for the test for enabling dev mode.
There is no such thing as a feature that doesn’t need documentation. Anyone who thinks so is asking everyone else not to use it
The documentation:
Put the leaves inside the cup
All lot of it is, without exageration, more at the
Put the proper side inside the cup
level of clarity: in other words just moving the “everybody should know this” element around rather than concretely just coming out and clarifying the bit that in the programmer’s mind is “obvious”.
If you’re specialised enough it can be really hard to tell what’s obvious. Like, you don’t want to do “grab the mouse, which is one of your computer peripherals” either. Or at least, I worry about doing something like that, and coming across as a dick.
It does say “leaves” and not “bag”
Then the user rips open the bag and pours the leaves inside
If a highly improbable spaceship had to dedicate all of its processing power to making a cup of tea, I suppose I can forgive an end user for having to think about it.
Tea, earl grey.
But what temperature?!
FWIW, my reference was to H2G2 and the Heart of Gold.
Yes, that could be a third option.
And pours the boiling water on its legs.
I mean that’s a valid way of tea drinking.
Appropriate that you used tea bags because it’s a popular legend that tea bags were created after customers misused the product. Some tea sellers started selling their tea in silk bags with the intention that customers would remove the leaves from the bag before use. Instead, customers dipped the bag of leaves directly into water.
polylactide, a bioplastic
So it does exist, and is cheap enough to use in teabags. Why not use it more, to pack vegetables snd stuff?
That kind of bioplastic tends not to biodegrade naturally, instead requiring a heated industrial composter with specially engineered enzymes added. If it’s disposed of properly, it’s great, otherwise it’s no better than traditional plastic but costs more. Also, not all bioplastics biodegrade at all as all the word means is that the source material is biomass rather than oil.
So even if you burn it with the trash, the C goes back to the natural cycle, instead of additional C we pump out of deposits of warmer times, we make plastic off. Still sounds better to me.
I write two forms of documentation:
One is an in-depth description of function, form and reason to understand and advance on the principles, stepping through processes and offering the opportunity to build on it if they choose
The other is designed for a hungover tech with a screaming customer on the line who just wants to know what to do to make it all go away.
The sort of end user that gets common sense stuff wrong is not the sort of end user that would ever have read the documentation anyway 🤷
I’ve had to interact with too many people who say this with a straight face.
Making apple pies is much harder cause you have to build a universe first. I just skip right past those recipes.
Reminds me of DMing an adventure that hinges on the party encountering teabags and hot water.
// teabag
// flail
“documentating” is not a word.
THIS IS THE STORY OF MY WORK
