15 ms·
Brown M&Ms, or Why No One Reads the Manual
- bowjack-deerman 6y agoAn often overlooked benefit of writing documentation (regardless of whether anyone will read it) is that it forces you to explain everything in a structured way and discover things that can be improved or simplified. Same principle as rubber duck debugging.
- m463 6y agoSounds similar to teaching a subject, or making a presentation about it. You will be forced to learn it very thoroughly yourself. "best way to learn something is to teach it to someone else".
- ChrisMarshallNY 6y agoI have found that the best way to create perfect software, is to teach it to someone.
- m463 6y agoTeaching someone about perfect software can only be done in lisp, grasshopper. :)
- perlgeek 6y agoI totally agree. When I write documentation. I'm often at a point where I ask myself: do I document this small inconsistency/inconvenience, or do I just remove/fix it? Often enough it's easier to make things more consistent than both documenting the inconsistency and getting people to read the docs and stop asking about it.
- mark-r 6y agoI remember well one time long ago when I did that. I had done the firmware for a piece of hardware that had some DIP switches to configure. I was having trouble doing the documentation for what each switch did and when you would want to configure it a particular way. Finally I realized it was because the switches weren't laid out logically, so I wrote the documentation the way I thought it should work then changed the code to match the documentation. Win-win, easier documentation and easier to use hardware.
- Stratoscope 6y ago> "We've just made an offer to a new writer", [Chris Espinosa] told [me (Andy Hertzfeld)], "someone who I think will do a much better job on the technical side of things, since she used to be a programmer. Her name is Caroline Rose. I'm going to assign her to the window manager documentation and see what you think." > The next week I sat down to meet with Caroline for the first time, and she couldn't have been more different than the previous writer. As soon as I began to explain the first routine, she started bombarding me with questions. She didn't mind admitting it when she didn't understand something, and she wouldn't stop badgering me until she comprehended every nuance. She began to ask me questions that I didn't know the answers to, like what happened when certain parameters were invalid. I had to keep the source code open on the screen of my Lisa when I met with her, so I could figure out the answers to her questions while she was there. > Pretty soon, I figured out that if Caroline had trouble understanding something, it probably meant that the design was flawed. On a number of occasions, I told her to come back tomorrow after she asked a penetrating question, and revised the API to fix the flaw that she had pointed out. I began to imagine her questions when I was coding something new, which made me work harder to get things clearer before I went over them with her. https://www.folklore.org/StoryView.py?story=Inside_Macintosh.txt https://www.folklore.org/StoryView.py?story=Inside_Macintosh...
- derekp7 6y agoThis is similar to what I've found, in that writing documentation for a product before I've written any code actually makes the product turn out better. When in design / development mode, I tend to think of all kinds of "cool" features to put in, but since using them requires knowledge of my state of mind at the time I designed them, it gets very difficult to document these features. So I end up writing the end-user documentation, then build a specification from there (functional requirements), then work on the technical design while prototyping various elements. Stringing together the prototypes often then ends up in a finished product.
- rurp 6y agoI've only posted about 1/3 of the Stack Overflow questions I've written. Forcing myself to break the problem down into a clearly explained question often brings a solution to mind or at least gives me a few new paths to go down, which often leads to an answer.
- dpc_pw 6y agoAnother tip: when writing communication (like email), start with TL;DR. Explain quickly who should read it and why. Start with the important stuff first, follow up with details and less important stuff.
- karimmaassen 6y agoWithout actually writing 'TL;DR' though. A well written email, letter or anything really, usually starts with the gist of the message. "Don't waste people's time" by fluffing up your texts. (Unless it's a novel, but then the goal is to build up a story to an apotheosis)
- mjlee 6y agoThat's a common practice in the British military. Normally abbreviated to BLUF (Bottom Line Up Front.) Start with the actions the reader needs to take (be at point x at time y wearing z) and then go in to specifics and reasoning.
- erikbye 6y agoGood writing avoids Internet memes and Reddit speak.
- solarkraft 6y agoNice writing includes cultural elements.
- MereInterest 6y agoI usually write an email in the order that I am thinking on it. First comes a paragraph or two of the details of the problem, then concluding with a sentence saying what I would like the recipient to do. Every time, I then go back and move that concluding sentence to the top. That way, the email starts with what I would like to happen, and if the recipient doesn't have any objections, the remainder of the email can be skipped entirely.
- epage 6y agoNot just tl;dr but as a pyramid. In US schoolsg english classes teach writing as an inverted pyramid where you give details (pyramid base) and end with a conclusion (pyramid point). In contrast, technical writing and journalism teach an inverted pyramid where you start with the conclusion (point) and fill out the details (base). Think of The Atlantic long form articles contrasted with traditional newspaper frontpage stories. The Atlantic is telling a story to build context before getting to what you wait. A newspaper article tells you who was murdered with what and where and then builds up more context.
- dontdieych 6y agoI'm cable guy. If you are working on data center, there is chance we already met. I've crimped so many RJ45. Can't count. Before CAT6 it was simple. After CAT6, all vendors starting produce their own. This is my best manual all time. I love Penduit manual. http://www1.panduit.com/heiler/InstallInstructions/N-COPN295--RevK--ENG.pdf http://www1.panduit.com/heiler/InstallInstructions/N-COPN295...
- ponker 6y agoWhat changed with Cat6?
- arnon 6y agoThe crimping technique and the size of the conductors
- kozak 6y agoAnd for all the perfectionists out there, this perfect manual has a typo in figure 9 at page 2.
- jagged-chisel 6y agoNah, that's fine - you just have to read it with the correct accent
- dontdieych 6y agoThe beauty is I even tried read. Just look figures then done.
- skibbityboop 6y agoDo you ever see places running T568A? I've never seen anything but B in 22 years of IT work.
- dontdieych 6y agoRarely. For old hardware. Cross cable. One end is B other end is A
- barbegal 6y ago> If any brown M&Ms were found backstage, the band could cancel the entire concert at the full expense of the promoter. I really don't think this would stand up in court. Does anyone know of any concerts cancelled due to minor issues with the rider?
- baddox 6y agoI don’t think it would matter whether it held up in court, because superstars probably had much more power and leverage than concert venues so the venues wanted to keep them happy. I also don’t really buy the explanation that brown candy would indicate that the facilities weren’t structurally/electrically safe. I think it’s more likely that the band were just a bunch of spoiled jerks.
- cjhveal 6y agoThe brown M&M's were supposedly a canary that prompted a line-by-line check of the technical specifications of the production for errors, which would then be the grounds to cancel the show. Snopes has a good article[0] on the Van Halen rider. [0]: https://www.snopes.com/fact-check/brown-out/ https://www.snopes.com/fact-check/brown-out/
- quietbritishjim 6y agoIt is also explained in the article. The whole point of it mentioning brown M&Ms is because of this.
- barbegal 6y agoI understand its purpose as a canary. I'm just questioning the idea of "cancelling the entire concert at the full expense of the promoter" which seems false.
- huffmsa 6y agoLikely they wouldn't, but if during their line chrck, they found other more dangerous omissions and failures by the promotor to setup the stage and equipment correctly, they definitely could cancel. These guys were working with thousands of amps of electricity, hundred of pounds of equipment, pyrotechnics,etc. Could easily severely harm or kill someone if it wasn't setup properly. No obligation to do a show of the other side of the contract isn't being fulfilled
- pmlnr 6y agoI miss good `man` pages.
- tuatoru 6y agoMe, too. What error codes does the program return? How about some non-trivial examples of use? And does the man page actually document the software? All the switches, all the enumerated options and data range limits for each option? In OpenBSD: all that is there. A documentation bug is a bug. In Linux: "best wishes, and perhaps you'd like to write the man page for this utility you use once every two years?" Disclosure: I use linux (through sheer inertia). I started on FreeBSD though, and got used to having adequate documentation.
- skibbityboop 6y agoThe worst thing you can see in a Linux manpage: "For complete explanations, see the info(5) documentation"
- bryanrasmussen 6y agoNo one reads the manual as a conclusion is belied by the use of brown M&Ms as a canary - if no one read the manual then it would not be useful to have a canary because no one would read it and then everyone would have to check stuff to make sure it worked before performing themselves and there be an extra charge to venues for this check. The fact that some people do not read makes a canary useful. I guess the title making a rhetorical point just flips my logic sensor.
- sixhobbits 6y agoNo one reads manuals (unless they're written using our documentation tool) is the point here.
- bryanrasmussen 6y agoVan Halen anecdote predating tool also shoots that point down though, but I guess the deeper point about Van Halen is at any rate people got to make money, so I guess I should forgive Nuclino the rhetorical bombast.
- InfiniteRand 6y agoMaybe the documentation equivalent would be to have a program halt early on and ask the user to perform an action detailed on X page of the manual, so the user would need to at least acknowledge the existence of the manual before getting anything done. Not sure if that would just piss off users beyond toleration, but it's an interesting idea.
- jacquesm 6y agohttps://news.ycombinator.com/item?id=7754334 https://news.ycombinator.com/item?id=7754334
- dang 6y agoIf curious see also 2018 https://news.ycombinator.com/item?id=18643258 https://news.ycombinator.com/item?id=18643258 2011 https://news.ycombinator.com/item?id=2839581 https://news.ycombinator.com/item?id=2839581 2009 https://news.ycombinator.com/item?id=743860 https://news.ycombinator.com/item?id=743860
- mothsonasloth 6y agoI thought it was Ozzy Osbourne who required 1000 brown M&Ms in a brandy glass? :)
- DoubleGlazing 6y agoA few years ago I left the company I was was working for. We had an internal doc wiki that hardly anyone used. I was one of the ones who did and I would document code changes and things like how to setup a dev environment and to list known gotchas. During my final week when I was doing code handover I sent an email around the company pointing out that the wiki would answer most of the questions they might have about the apps I worked on. Three months later my phone starts ringing. I was in a new job so I didn't answer, but they kept ringing. Then they started calling my wife as she was listed as my next of kin. My wife also didn't answer as she was with a client. After a few hours, my wife picks up the call and texts me that my previous employer was desperate to speak to me. So I called them during break and after a bit of an ear bashing I was informed their whole warehouse system was down and all business had stopped. After a bit of diagnosis I realised that they had fallen for the first gotcha I listed in my docs, they deployed the wrong DB driver. I asked why they didn't read the docs. They responded "what docs?". I explained that I sent an email round before I left with guidance on the app. Rather than apologise they berated me for not doing more to alert people to the existence of the information. It was that attitude that contributed to me wanting to leave the company in the first place. I think the moral is that no matter how good your docs, some people will always ignore them even when the world is collapsing around them.
- wheelerwj 6y ago> after a bit of an ear bashing you actually helped them? Hang up, charge your emergency hour consultant rates, and tell them you're available once they sign the agreement.
- DoubleGlazing 6y agoThat's what my wife told me as soon as I got home. If it ever happens again that's what I'll do.
- WrtCdEvrydy 6y agoI've actually done worse to a bad employer... I picked up the phone, said my name, and as soon as they dropped that, I said "Oh, he's dead" and hung up. My former boss sent me a text later going "Very mature, but very funny" Edit: Boss was the only one who had his head on straight
- greatpatton 6y agoThis is quite strange, having organized a large music festival this kind of document were split among different teams. Meaning that people in charge of the backstage are managing their part (getting food, M&Ms, specific brand of beer, and other non nonsensical request, etc) and the people in charge of the stage and technical stuff are taking care of technical requirements (and aligning them between different bands sharing the same stage). So if someone from the backstage team messed up the M&Ms, it will bring absolutely no information about how the situation was handled by the guys in charge of the stage... So this canary will be quite ineffective in reality
- sokoloff 6y agoIf the backstage team didn’t miss the M&M detail, does that give you any information about the overall attention to detail of the promoter? (If it does, then it seems like the lack of that information is itself information.)
- willcipriano 6y agoIt can tell you something about hiring practices. The quality of the host of a restaurant probably shouldn't tell you about the staff in the kitchen, but in reality if they made the choice to go cheap in the front the the house they also very likely made the same choice in the back.
- lebaux 6y agoI did my share of event management and I disagree. It shows how well the teams are managed and attention to detail. Of course, you should probably have more canaries.
- MisterTea 6y ago> So if someone from the backstage team messed up the M&Ms, it will bring absolutely no information about how the situation was handled by the guys in charge of the stage... Sounds like there was little to no organization then. I showed this to my co-worker who managed the technical aspects of a large college theater that also served the town. They hosted multiple large events including bands who had fleets of semi trailers to haul their gear. They had a single contract review person who read everything carefully and then coordinated the teams doling out requirements. As each team satisfied the requirements they would report back.
- turbinerneiter 6y agoI write documentation for myself, because my brain is broken and I can't remember anything. Also big Polaroid fan.
- gpmcadam 6y agoThis is an ad.
- bullen 6y agoI haven't read manuals ever, but last month I bought bluetooth headphones so to pair them I first tried without reading, and failed. I opened the manual to find it was many pages of legal text and just one phrase of instructions: "hold button for 5 seconds until light is blue" and that failed too. I mailed support and the instructions then came back as "hold for 20 seconds, until light first becomes white, then blue", I simply mistaked the white led as very light blue. This is why people don't read manuals!
- koala_man 6y agoThis has also been my experience writing documentation. You write "hold button for 5 seconds until light is blue", and someone will hold the button for 3 seconds until it turns white and ask why it's not working.
- bluGill 6y agoI'm color blind so don't blame me. If it turns white then blue I can probably see that, but if it turns white and there is no warning it goes through white before blue I'll assume you just got a different led on the line.
- koala_man 6y agoIt's fair to assume that the docs are simply wrong/outdated about the specific duration and color when it works, but I would start to question those assumptions when it doesn't. Pedantically proving instructions wrong (e.g. with a stopwatch and colorimeter) is a great way to submit a useful bug report with solid steps to reproduce, and a lot of the time it ends up solving the problem as well.
- bluGill 6y ago20 seconds is long enough that I will not wait that long in general. When something else happens in 3 seconds that seems like it could be right I might wait 5 more seconds when it doesn't work, but not 20.
- tomp 6y ago> We are impatient and have a shorter attention span than a goldfish. To be properly absorbed, information needs to be organized in a way that accommodates that. Common myth, but actually not true. Joe Rogan has 3 hour long talks with people and is one of the most popular media figures. The real truth is, most information sucks (it's both useless and boring), so people tune out. Improve information, get more attention.
- high_5 6y ago> Improve information, get more attention. Clickbait all the documentation! ;-)
- tomp 6y agoI'm not so sure... just, like, maybe put one single thought into organizing it? I still hold PHP documentation as a golden standard even though I haven't used the language in like 10 years. Everything is spelled out, and what's still unclear, there's usually a comment or two at the bottom of the page asking to clarify just that. Contrast that with Python, my current main language... not only is it badly organized as a whole (where do I find documentation for `str`? Surely there's a page... no! it's all bundled up together in "Built-in types!"), the individual pages _also_ have no sensible structure and not even a good TOC! Python's jumping between versions and deliberate refusal to back-port features doesn't help either, but that's a different topic...
- rsa25519 6y ago> I'm not so sure... just, like, maybe put one single thought into organizing it? Most documentation definitely needs more attention towards organization. But in my experience, organization is extremely difficult, especially because a documentation author may think of the system very differently than a new user might
- cardiffspaceman 6y agoOP should have sent an email titled, "One weird fact about the DB driver!"
- gwbas1c 6y agoAt my old job I used to flip my lid whenever I got a ticket (from QA) without logs. It was for this exact reason. Someone filling out a bug without collecting logs was usually missing a lot of vital information needed to diagnose and fix the bug.
- RegW 6y agoAs a developer I'm a fan of checking the documentation into the same source code repo alongside the code. If the code branches the documentation branches, if it merges the documentation merges. Documentation can then made to be part of "code complete" for developers. Think README.md However, there's always resistance to this wacky idea. Chief being the lack of tools and management fear of editing text files. This article also adds searchability to the negatives.
- quotha 6y agoActually, a lot of people read, most of the time there were no brown M&Ms and the stage was set up correctly.
- watwut 6y agoI always read manuals and they are pretty often crap.
- Pamar 6y agoI don't think much of this article. The Brown M&M example seems a bit convoluted and anyway "what to do instead" is just a bunch of platitutes. "Write doc to make it searchable" ... ¯\_(ツ)_/¯ In my experience one of the big problems (I just had a call from one of my users demonstrating exactly this point) is that often there is a disconnect in terms of vocabulary. What the business calls a "refresh" of System X123 could be any of "full copy from prod of the whole X123 data", "can we please just import the subset of data I created in X123 Test?", "X123 provides a sort of materialized view of the sale prices to Z567, but it seems that the view is outdated, can we please refresh that"? This happens (albeit less severely ... "usually") inside IT itself at least when the organization gets over a certain size. So dataset are named with their content, but the actual content might change scope or the part which is more relevant varies for each consumer, therefore both the provider and the N consumers tend to refer to the same thing with slightly different names while the "correct" name is already used for something else in different context (e.g.: "Sale prices" - is it now? future? historical? only for agents? only for a specific country/market...?). Even just having a single, unambiguous lexicon would help a lot (and would make the "searchabilitly" a bit less mythical) but I don't see this or similar points addressed, while apparently the detail of the sound and light equipment deployed by Van Halen seems to definitely require some space.
- yjftsjthsd-h 6y agoI once had the joy of working for a company that had rebranded its own products, sometimes multiple times, and was inconsistent about which name would call things by. Oh, and several products had similar names and would be abbreviated to the same thing. Helpdesk spent an insane amount of time just finding out what product any given ticket was actually for; they had a document that tried to to list all products and all the names that each product was known by and who a point of contact was for each product, but it was incomplete and didn't necessarily have enough information disambiguate many cases.
- Pamar 6y agoWell, yes - this is a somewhat extreme case but the problem is the same even for internal-use-only corporate systems. And it becomes even more acute when (as it is my case) your first language is not the same originally used to develop the first version of the system. (Imagine an ERP system built in UK and adopted and customized by a French company, for example: IT would probably use 20% of French terms/names, the rest will be in English... Business will do the opposite).
- im3w1l 6y agoJust replying to the headline, but the people don't read the manual because software is now intuitive enough that they don't have to.
- commandlinefan 6y agoExcept for the software that isn't. Which is the only software that reasonable knowledge of is valuable.
- commandlinefan 6y ago> Properly reading the docs can take hours, and most don't have that much time to spare. And, reading the docs looks to an external observer exactly like playing video games or browsing facebook all day. Modern "agile" organizations dedicate two or three watchers to each actually productive employee to "make sure" that the productive people are actually being productive. This means that the only time spent on tasks is spent on tasks whose outcome can be quickly, easily externally observed. That this necessarily produces a substandard product seems to be unimportant.
- doorstar 6y agoI just faced this - I was trying to write a somewhat complex MongoDB query and I decided it was finally time to read a book rather than just cutting-and-pasting from stack overflow until I stumbled across something that seemed to work. So of course in our status meeting yesterday I had to say I hadn't accomplished anything. In the long-term it's good to have someone on the team who really understand MongoDB. In the short-term it looks like slacking off. - Of course my conclusion after reading about MongoDB queries was to decide that I wanted as little as possible to do with MongoDB queries and am going to avoid them at all costs.
- grimjack00 6y agoYou read the book; you're now the expert.
- WarOnPrivacy 6y agoThe article confirms a couple of principles that survived largely intact from my youth. I'm most efficient when I'm 1) in service to someone and 2) prioritizing their needs. This applies to pretty much any interaction with people - but especially to personal relationships like family and parenting.
- annoyingnoob 6y agoI always write the docs. I point to the docs when I get questions. Most people skim over the once and then just ask questions later when they forget. I don't like being a human encyclopedia.
- mitchdoogle 6y agoI'm tired of advertisements posing as blog posts. Can Hacker News include a notice on posts like these?
- Havoc 6y agoI love this story. At the same time I also thing its a little overly complicated. Used to be an (amateur) sound tech & realised pretty fast that stage stuff is an industry where its incredibly easy to tell who is on the ball and who isn't. I find it very hard to believe that an experienced band can't just stroll across the stage with a can of beer & know the answer 20 seconds later. No M&M contracts needed. Still cool story with a good message though