4mo ago

no amount of documentation can save users from themselves

85 comments

Hmm ... Better pigeon hole clients into only using the teabag.
"Why can't I put the label in the water?!"
- Our legacy system always puts the label in the water and our clients rely on the faint cardboard flavor.

Smart developer: let's make the label an 8 inch square so it won't fit in any mug.
- End user: makes tea in a large pot, to fit the label.
  
  Developer: THATS IT WE’RE A BROWSER BASED APP NOW!
  End user: why can’t I run this on my AOL account?
- User: Folds square in half to fit into mug.
- Huge waste of material on the label.
  Since the labels are larger, the boxes for those tea bags will need to be larger too. That incurs in additional waste of material and storage space.
  People working in markets selling those tea bags will complain. Now their boxes don't fit in the aisle alongside boxes with tea bags of other brands.
  Customers will find it clunky and convoluted. Some will understand why the dev did it, and get angry - because from their PoV it'll sound like the dev is saying "I assume that you're a muppet, unable to distinguish the label from the bag".
  And some will still do like others said: use a larger pot, fold the label, etc. Defeating the purpose of the change.
  There are plenty situations where you can be smart. This is not one of them, stick to standards and document it properly. "This is the bag, it goes in. This is the label, it goes out."
  (Not that it changes much for me. I'm still ripping the tea bag apart and mixing the contents with my yerba mate. Unexpected use case!)
  
  tea_bag.unwrap()
- Just get rid of the label altogether. I'm always suspicious when a teabag has a string on it.
  
  You aren't supposed to leave it in the water the whole time.

- What's this from?

I design optics and I've seen a return request because they "couldn't see the target" and included photos to show what they meant. The customer installed it backwards and didn't bother trying the other way.
- If it can be mounted both ways it should work both ways. 🤷‍♂️

And that's how an iPhone with an interface that even a toddler can figure out sold a few billion units.
- As someone who's used and uses both for work and isn't a fanboy of either, sorry but apple does not have an easy to learn interface. It seems like every single choice they made was done to just be different from the alternative, more often than not to the detriment of the user. If they lock people in to how their ecosystem works low tech people can't easily change.
  
  If they lock people in to how their ecosystem works low tech people can’t easily change.
  Other people can just mimic the iPhone interface. That's basically what Android did.
  The real difficulty of switching to another device from Apple is the multi-year contract that the phone companies try to get you on.
- At what cost, though? I thought the generations after the millennials would be more tech-literate. But after seeing Gen Zs around me at home and at work, things are just regressing.
  
  It was inevitable. We took a mishmash of things that kinda worked together with a patchwork of software and shoved it into a streamlined define with a custom made interface to tie it all together. One of those things pushes the user to learn more, and it’s not the finished and polished product.
  
  Can't really blame them either, it was our generation that dropped the ball in making sure they were more tech literate than us. Not that I have kids but still.

A proper engineer would make the tag absorbent and use the principle of capillarity to transfer the water to the bag (and the other way round once tea flavoured) to cover this case.
Users can't avoid being stupid, but a proper engineer should be able to cover all cases.
- This assumes an infinite timeline and budget.
  
  Well, no proper engineer will agree to less than that
  
  And also the existence of a perfectly insulative, yet durable and long-lasting sheath for the bag and string. I realise it's just an analogy, and in cyberspace that sort of thing is trivial, but with real matter it's beyond a pipe dream.
- No, that complicates things way too much. Simplicity in design is beauty. A real engineer would recognize the tag on the string not only as a point a confusion, but also a superfluous feature. Simply remove it. The end user will have to use a spoon supplied by themselves to remove the teabag, but thats their problem. At least there is actually tea in the cup at that point.
  
  Loose leaf tea is peak design.
- Or the pg tips approach: 'd'ya know what? No more tag or thread for ya now you've got to fish and pinch the baggy out of your scolding tea ya wanker'.
- So you're saying it should wick the water from the cup to the table like an oil lantern. That seems like a good way to have half of your cup on the table.😂
  If you get it to travel up the string, gravity will definitely do the rest. It seems like such a passive aggressive way to design a product and I'm all for it.

Idiot proofing just results in a better class of idiot.

I can be an idiot every once and a blue moon. Thank you to anyone who put literally everything a manual just in case someone is braindead and isn't afraid to rtfm.
To be honest it's just after I've spent 10 hours on something fairly complicated and new to me. I suddenly can't think for myself anymore. It literally becomes a chore to do the simplest shit sometimes.
- Honestly, if you read the manual you are very much not dumb
  
  I do appreciate it, I know I'm no idiot.
  To be honest, I kinda wish some projects came with API manuals. I understand it's not a priority in an open source project with limited resources.
  It would be nice to use a python based ml tool without passing commands through it via shell. People do it, I just don't have the time or experience to analyze a complex project like ML voice synthesis.

- Even worse: It's only a paper tea.

If you have access to any kind of UX and UI folks, you automagicallly get a leg up on this, y'all. It is goddamn amazing.
Single dev on a personal project? Go find someone in the community who has an eye for design or hit up a design forum. Work has you on a project with only two other devs and limited resources? Ask for a favor from the UX team down the hall.
We are all tryna make good experiences out here. Let us avoid getting 'teabagged.'
- Basically you have to hide all choice behind a settings page. Think of a cattle chute that only let's them go one direction to the bolt gun. Wait...

Send multiple all user emails stating which end to put in the water. People still call the Help Desk or email you directly, your response is forwarding them the email, they complained that it's not convenient or they get too many emails or don't have time for emails.
You send documentation and place it on the portal. they complain it's overly complicated, so you add screenshots with which end to put in the water. They still mess it up and complain about lack of instruction.
You schedule 30 minute courses, 3 times a day, every day of the week and spam out notifications to sign up. You get a total of 12 people the first 2 weeks, most of which figured it out on their own at some point but thought it was mandatory, or that there were high level secrets or Tips n Tricks you were gonna teach. When the education period ends, you still get people complaining that the times weren't convenient enough for them because they work 2nd shift or weekends.
You schedule another 2 weeks of classes, after hours and on weekends. 2 people show up, but not the ones who removeded about it.
Despite everything, your boss still sings you on your review didn't meet the needs of the organization with this rollout
- Oof, I’m not in IT thank goodness, but I still feel this in my bones. I’ve had to write plenty of instructions for in-house trained users though, and it seemed just as bad. I can’t imagine what it’s like with real randos.
  I’ve definitely seen some of these “please let us help you” getting sent around. And even in completely different types of organizations I’ve seen time and time again how the obnoxious entitled complainers don’t even show up.
  
  They're just serial complainers. Even if you walk around their department with a laptop to give them 5 minute instruction, no matter when you do it it's always inconvenient to them. Some people exist solely to complain about shit

Speaking as a user (I'm not a programmer even if I'm often loafing around here):
Left is not "optimistic" but "assumptive" - blame the dev and the user.
\ Right is not "pessimistic" but "diligent" - blame the user.
But the worst type doesn't appear in this pic: they'd put a ball of chicken wire around the label so it's physically impossible to put it in the hot water.
- I'm not a programmer yet even if I'm often loafing around here
  Fixed that for you...
  Join us on the dark side. We have cookies.
  
  Clicks Accept Cookies
- Then the users would complain that they can't fit the tag in their water.
  
  We're talking about the worst dev, right? "No, chrust me. I have a vizhun about how the tea bag should be."
  Incidentally it's the same answer that he'd give to people annoyed who neither need nor want the chicken wire ball.

Documentation be like:
For (literal string) place for i = T end of and rest unit 4

`

if ( parameters.teaMass <= TEA_BAG_WEIGHT ) { return "Error: incorrect input. Check if tea bag was inserted correctly into water container." } `
- And then a user starts adding weights to the label until it passes.
  
  unlikely
- #define TEA_BAG_WEIGHT 0

I write graphics software that almost seems intuitive, until you realize I gave it a split personality.
Even I forget about the split personality side of it.

I don't even work in IT but I make complex Excel tools for my Finance team.
I get an email about once every week or two from one of my coworkers asking what to do about an issue. Nearly every single issue would have been resolved if they just read even the first few instructions.
My favorite is a specific tool we use to review the financials. It relies on Scripting.Dictionary which is only present in .NET 3.5.1 or prior. The very first instruction on the file says you need to download it. There's even a very handy button right there which will take you to our software center to install it.
Yet every single time someone gets a new laptop, they immediately assume that the file is broken.
- If you hear about it that much, why not make the script check for .NET before crashing?
  
  It's not worth the effort and testing. People would only experience it once every 3-4 years, depending on when they get a new laptop. Must still shouldn't have to worry since other software would install that version of .NET already.
  Plus, people don't bother to read error messages anyways. Another tool I created would create PDFs of the financials. The first section would be pulled from the EPM and the second would be a data dump of every transaction for each cost center. If the totals don't match to the dollar, the script would throw an error.
  90% of the time, it was because the EPM data was being refreshed as it's scheduled to do so every half hour and takes 3-4 minutes. So I had the error message tell the person to just go take a quick break and come back. Still, people would email me saying they don't understand why they're getting the error and it would always be fixed if they just wait.

I'd* better write some documentation
- Using better by itself is fine in an informal context, and "had better" is only required for formal contexts. And I don't think a meme on the internet counts as a formal context.
  And also, 🤓☝️
  
  That'd be a contraction of 'would' in this case, wouldn't it? As an ESL speaker I used to find these grammar 'mistakes' (for lack of a better word) made more difficult for me to parse the sentences. As with code 'written once but read many times' would apply here.

You're calling this person stupid, but they're 90% of the way to getting it right.
If only every technical problem was this easy to solve.

"I'll add this to our knowledge base and other people can assist now!"
"Hey So-and-so, it looks like you our are guru at this issue, can you take a look at these 4 users who mentioned the software in their ticket?"
I just need to make progress on my projects, stop giving me desktop tickets pls :)

you forgot
end user: this product is defective; the developer should be fired

no amount of explaining http errors and windows terminal commands can save my friends from trying to refresh browser on a 5xx error and asking how to exit cmd

85 comments