A 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.
First thing you do is email them a contract with a _reasonable_ consultant hourly rate. You literally handed them documentation in advance and they didn't bother to read or test it. Don't feel bad, don't get angry, get paid.
If you are contracting in a situation like this a reasonable rate could mean $250-$1000 an hour. Really depends on what kind of money your currently make.
A better approach in the case would be to offer to investigate, and provide a flat rate. You can charge $3000 flat fee, and you may solve it in 1.5 hrs.
Oh god yes. Otherwise it's always the same: try to bargain you down to billing 30 minutes work, then complaining that you didn't do the 1.5h of work they'd agreed wouldn't be done to save costs. The usual "in lieu of paying you more, we'll complain harder" nonsense every client from hell pulls.
Or just set a day rate, and limit scope to helping with the specific problem. "It's $1200/day, and scope is limited to helping you understand how to recover from the described problem. All of the work recovery work will be done by you, and my role will be limited to advising."
If someone from my old employer calls and asks me politely for a bit of help with something I know well, I'd help.
If they call to yell at me about how I left behind a fragile system or how I left them in the lurch by quitting, the correct response is to tell them to get fucked, if they then ask for help after that, the correct response is to tell them to go fuck themselves.
Normalising that kind of abusive behaviour is not going to improve the lives of the co-workers you left behind.
That would cross my mind. Most potential employers I've encountered have usually asked for references from my last two jobs. On another occasion I had to undergo a background check which involved contacting my last 15 years worth of employers. So no matter how much I may have disliked an employer I would be unwilling to burn bridges until I knew I would never need to rely on them again.
This is why you cannot get anything more from your previous rmployerd than a certificate of work in France.
If they call and ask they are in complete, dangerous illegality (I had once an American company czll me about an ex employee and they could not understand that).
Some companies used to ask for references, they were referred to friends and they do not ask anymore (this is a general case).
Most people won't give a bad personal reference anymore because they are too afraid of being sued. We just say yes, the person worked here from this time to that time.
This is a cliche but it can't possibly be true. I mean, it is extremely expensive to file a lawsuit, you probably lose, and nobody will ever hire you again, because it is public record.
Even if they're being a bit unreasonable, the momentary satisfaction of telling them to F Off is probably not worth the risk of it coming back to bite you some day.
If you don't want to tell them to F Off for this reason, you can contact their line manager, HR or customer service department and ask them to do it for you.
The kind of person to lay into you like this is not going to give you a glowing reference whatever you do.
That is probably true. What I meant is that I would simply break off the conversation at that point. And, yes, if they kept pursuing it, I would either contact their manager if I had a good relationship or have HR tell them to knock it off.
Spending 10 minutes on the phone to answer questions is one thing, as long as they are respectful, but more than that means that they want you to work for them.
Theoretically maybe. In practice, no one to a first approximation is going to have an issue with you spending an hour helping a prior employer with some cleanup related to your prior job. Employment agreements tend to use words like outside employment/consulting/etc. They don't (and it would probably be unenforceable if they did) generally forbid you from talking to a former employer.
In some circumstances, it may even be violating your termination agreement with the former one.
Often, if made redundant by a company, you cannot return to work for them (as employee or contractor) for a year, otherwise you have to pay back your redundancy pay.
That leads to a potentially hilarious conversation about rates.
"I'll do it, my rates are 100 per hour plus 10K if you want me to start before June next year"
If that's a contractual obligation between them and you they just need to waive it in writing so that you're protected.
That being said, the issue with redundancy packages is that taxes are involved and those guys will be inflexible if they find out that your package turns out not to be tax-free after all.
I don’t think it’s rude to give them your rates.... but then again I have been only working with consultancies for the past 15+ years, so even in house work gets a billable rate attached to it.
Anything that takes more than an hour should be billed. If the guys at the company are really your friends, they would fight to see you get paid.
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
I know a woman who did this but to credit collection agencies. One day the police showed up at work and arrested her for fraud. Obviously not the same thing as you had no contractual obligation to them, but telling everyone you’re dead is generally a bad practice.
What would I bingle for if I was looking for a template for such an agreement/contract? It seems like the kind of thing you would want to have prepared in advance (in case of emergency, break glass).
Yes! In my experience a well-crafted SOW is key to the practical understanding between client and contractor. Good SOW language is clearer and, IMO, psychologically less daunting to negotiate than contract language. The SOW provides a roadmap not just for the project but for the writing of the actual contract.
Wow, that is exactly my Story, up to the jdbc driver!!
That was the first time they called.
I made a perfect confluence-wiki, for every server a page, for every application on that server a sub-page.
The Code-repo-links the config's the howto's everything was in there, the second time about 2 month after i went for the other job, they floded a Oracle-Db, called me and asked really rude what a shit installation i made, so i asked for the server pointed them to the Wiki-site and the first sentence boldly written said: DEV-VM -> DB-scheme-migration (DONT put DATAS IN, 20GB-DISK)
In this case the server app had multiple DLLs imported from other projects and they had been compiled against a specific version of the Oracle .net driver.
My docs clearly stated that you should not update the driver unless you were willing to rebuild all the other projects as well. I could only deploy one copy of the driver file, so it had to be the version all the different parts of the application were expecting. It was an old app, whoever started development on it didn't know about repositories and DB singletons - there were DB connections all over the place.
The annoying thing is that the .net error message they were getting actually stated what the problem was in fairly clear terms, yet they still called me.
A good story, and I find myself in a similar position (the one who writes the docs). I think a lot about this topic, because as our company grows it becomes more and more important, and more and more difficult to impart all of the scattered knowledge on new hires.
I really enjoyed this read. I think it contains actionable suggestions that I will incorporate into my job. Consultable documentation, all in a single location sounds like an improvement over what I have now.
The focus of my approach has been a bit different so far: since I know that nobody reads the manual, I strive to make the manual short: "Run this one command and it will do everything for you." My thinking is also that it lowers the bar of skill for new hires. There are some unfortunate consequences of this:
1. Maybe we don't want to lower the bar of skill after all (maybe we do - good workers are hard to come by where we are).
2. I am something of a single point of failure. If I go, I'm sure things will still get done, but it won't be done well (very subjective of course).
Anyway, I'm excited to try and improve my processes to make it easier to grow.
I agree with both (1) and (2). We require all devs, as a part of the onboarding process to read, improve and correct the docs for onboarding for each new hire. A PR is required. This forces all developers to understand what happens when something actually breaks and also how to locate the information, should the need arise.
This is also why we've never Dockerized. It masks too many issues and no one seems to have a clear understanding of how all the garments are stitched together.
Very much this. New hires must always be tasked to improve onboarding documentation. At a previous place I worked, I went from expecting it to take a new hire several months to be productive to less than a couple weeks and a big reason was continuing to have newbies tweak docs and fill in details that might be easy to gloss over by soneone who already knows the tech.
As for containers, I’m not sure I follow. We ended up using vagrant and then test kitchen for our VMs, which really helped with on boarding. The team had too many people who couldn’t be expected to troubleshoot much of the backend anyways. We had stayed away from containerization because it added complexity without any clear benefits for our use cases. But test kitchen definitely papered over the need to get a local environment running with all the dependencies, which might change with different services, and that seemed like a good thing.
I can maybe give some idea of what he's saying about containers. We do use Docker, and when I mentioned in my original comment that I aimed to lower the skill required to come onto a project, Docker is the primary vehicle for that effort. Here are my reasons:
1. Nobody has to install dependencies. Docker is the only dependency (with compose).
2. Everybody has the same configuration.
3. Software versions are (mostly) tightly controlled. This requires whoever sets up the dev environment to make sure they use specific versions, and not :latest.
4. Devs don't need to spend time worrying about how the dev
environment works, just the code.
This means that my README for a project usually has a section describing setup that just says:
1. run `dev/install` (any libraries from eg. NPM, go modules, etc.)
2. run `docker-compose up`
3. Check that the application is running on port XX.
This actually works great, and it does allow new devs to get to work quickly, and it does allow us to use devs that know very little about the underlying software that we're using, unless something doesn't work correctly. And that does happen, much more often than I would like. Then it takes my time and theirs to get up and running, and that was definitely not the goal.
When I'm asked a question I often respond it is on the wiki. If it isn't on the wiki it is your job to put it there. If it is wrong and you know why fix it. If it is wrong and you fail to figure out why, then talk to me, but I won't respond except to say I fixed the wiki.
That way the wiki stays up to date. Most corporate documents/wikis are worthless after a few years because things change but the wiki didn't. You need to constantly update it.
I am a proponent of the lowest common denominator model of development. Basically this means that whatever you develop should be understandable by a relatively new or junior developer. You should develop in such away that a someone coming in off the street should be able to pick up where you left off with minimal effort. This is partly about code, but also docs. Think about the next guy/gal. Is your code clean and well commented? But do you also have docs explaining the bigger picture? Think about what sort of documentation would have helped you get up to speed with the project. If people have to use compile errors to figure out what needs to be done to get up and running then you could have done better.
But why are your instructions in the back closet when they could be taped directly to the code in the readme or in the comments and error messages? I've had similar phone calls, to which I respond "it's all in the README." Never heard from them again.
> Then they started calling my wife as she was listed as my next of kin.
Minor tangent, but that got me to wonder: would that be legal under the GDPR, which only allows you to use data for the (legitimate) purpose it was collected for?
In this case, they gathered next-of-kin info for (I assume) disbursal of benefits when the employee is dead or incapacitated. “To find the employee after he quits” would be out of that scope, then, right?
This was in 2013, pre-GDPR but in 1998 DPA territory. Yes, I do feel it was probably a DPA violation even back then.
In Ireland next of kin is purely for cases where the person has been incapacitated/hurt and someone needs to be told. Nothing to do with dispersal of benefits etc. There's a separate process for all that.
Sorry, yes, I forgot to include informing them of a workplace injury. And I assume GDPR wasn't in force there and then, just thinking of it as a hypothetical.
The 1998 DPA was still pretty strict. I have no doubt the DPA was violated when they called my wife.
I blame the manager who came from a sales background. His response to every problem was to "call someone", rather than have the team work out what was wrong.
I manage the "support" (mostly DMCA) tickets for some small website we run as a hobby project without monetization whatsoever (aka "for fun"). People are free to use it, e.g for chat and to share content (i.e. DMCA magnet). It's maybe like 5-20 such tickets per day, most of which are DMCA and can be handled really quick, so it isn't that much of a time drag.
Not actually getting paid/having an employer there can be quite liberating...
Since nobody who ever writes me is a customer, and I am not getting paid anyway, I am more or less free in what level of politeness I apply. I usually try to model my response after the initial requests I receive - taking into account other factors like people who might be genuinely upset; or confuse me with the person who actually uploaded a piece of content.
We have users from all over the world, and it's rather interesting to see particular patterns/attitudes with certain types of locales.
For example, Americans - by and large - are too lazy to read the few lines of text on our contact page detailing what information we need to address what kind of problem, and often are rather rude from the get-go, and really like to threaten with their lawyers (plural!) in the initial email when it comes to copyright or related issues. This then leads to me asking for the missing details, followed by a lot of them demanding to talk to my supervisor, to which I then point out that they are not our customers and that being rude or even outright insulting the only person who could potentially help them (for free) isn't maybe the best idea they ever had... And if the supervisor demand came up, I point out that I do not have a supervisor, I demand to talk to their supervisor instead.
It would be unfair to only unload on Americans, tho. We got a lot of Portuguese users, and tickets from the Portuguese are even more rude on average and of course nobody bothers to read the instructions, tho nobody ever demands to talk to my supervisor. The French are polite but like to make outrageous demands, but seem to read the instructions. Germans are "professional"-polite but tend to write LOOONG emails, and when it comes to copyrights usually cite a lot of completely unrelated laws, but again read the instructions. Middle/South Americans are usually polite but constantly think the Subject line is where all their text is supposed to go, and do not read the instructions. I'd say the most pleasant people are the East European (mostly Polish and Russian) people who write me... I don't remember anybody outright rude from East Europe ever, tho the language barrier - our website is English only incl the instructions - is often rather obvious (but I will not fault anybody for that, of course).
Point being: the level of RTFM in my limited experience differs quite a bit depending on locale.
An 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.
> "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.
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.
I 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.
This 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.
Sounds 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".
I'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.
> 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.
Joe Rogan is very light listening though. I doubt people actually sit in their armchair listening intently for 3 hours without doing anything else. People also love to binge watch TV - does that mean there’s no attention span issues?
Not sure about that... I’m just listening the Weinstein episodes (first Bret, not Eric). they’re talking about very controversial topics and going very deep - mainstream media would dismiss most of those as just “conspiracy theories” without even considering them rationally on their merits. I might be biased though, maybe those epispdes aren’t as popular as some other guests.
I think what people miss most in the “mainstream” narrative is honesty & truth.
I am watching and listening intently the ones that I am interested in. Episodes with Guy Ritchie, Robert Downey jr. or Russel Brand, I watched in full in one sitting. I can also watch bunch of episodes cooking, checking other stuff.
I'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...
> 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
And then proceed to a 37 pages long doc, where he explains the history of drivers since 1745, and repeats and repeats
Advertizement above the NEXT button which keeps shifting while the page loads
Little did you know that the driver is actually
You have reached your free limit of 1 article per month, SUBSCRIBE HERE, but the button shifts again and now you have porn and "you have a virus" popping out everywhere
And you want to leave but the back button id hijacked and you understand why the etymology of vi is an Aztec phrase for "how do I get out of this shit"
Agreed. I got excited about podcasts really early on because there are so many interesting deep dives on so many topics. There are exceptions but most traditional radio shows cover topics briefly, terribly, or both. The fact that podcasts have exploded in popularity is strong evidence that many people enjoy more detailed discussions on many subjects, they just didn't much access to them in traditional media.
And don’t forget, streaming service Quibi, with its focus on ten minute shows, failed to pull viewers away from the series and movies on HBO and Netflix that require much bigger time and attention investments.
This 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
It 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.
> 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.
This may be possible for a theater hosting a unique event, but never for a music festival, where you have like 30-50 different artists/bands on one night. There you have people responsible for each aspect. Of course you have a stage manager responsible for the overall operation of each stage, but there is no way that a guy can make sure that everything is ok in all details for all artists (the riders sheets can sometime several pages of different requests, like that hotel room must contains this kind of pillow etc.). As you say you have to delegate, and if one of the guys of the backstage team forget to sort the M&Ms, it will be a problem for the guy in charge of the backstage, but that's it. Like in any large organization, you cannot imply that because the customer support guy messed up that all the engineering team is bad. So here, if they wanted to make sure that technical guideline where followed it would be better to put something like: please mark all this kind of cable with pink and yellow tape.
In my experience doing video work for some of these type events, its possible for a music festival to negotiate riders that work for the festival an implement them properly, it might take a few more people and decent planning ahead of time.
The problem is that it requires a fair bit of documentation, coordination and processes to make it work, which some festivals do fine and I guess some just don't.
The key is that your head QA person knows who is in charge of what and has a process for holding them accountable, one such way would be to create a checklist of all the items that need to be checked, based on the riders, production requirements, regulations, expected amenities, plussing, etc.
Its also needed for each stage of the process, planning with stuff like speaker modeling, truss engineering, power load calculations, network and communication requirements, etc... on to checking the event area after load in and setup is complete and continuous checks on key items for safety and a reliable performance.
So, its certainly possible to reach an optimized state where you have a negotiated list of requirements and implement them correctly.
No 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.
Van 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.
Maybe 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.
I 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.
I 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.
Well, 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).
> 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.
I 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.
I 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 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.
You don't know the difference between white and blue for sure until you've seen both. I actually recently had more or less this problem trying to set up my cable modem (maybe it was something like is it blinking, pulsing, or flickering, but anyway).
I try to set an example by providing copious context but I don't feel like others imitate me. Sometimes I think I'm the only one who has a theory of mind.
I'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.
It'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.
20 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.
Did it need all 20 seconds? If so, the docs were definitely wrong and useless and I see your point.
My suspicion is that it works fine with 5 actual clock seconds (instead of "a short while"), and that they just said 20 so that even the most chronologically challenged would end up holding it for at least 5.
At 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.
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.
I 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.
As 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.
Another 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.
I 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.
Without 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)
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.
The 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.
I 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.
Likely 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
It's only to act as a canary, kind of a checksum (and I suspect it's not the only one, only the most obvious/curious).
When the band arrives into the venue, they check for canaries: if they see something wrong, it's a good enough reason to trigger a full inspection for serious issues.
I don't know how the contracts were actually written, but I suspect it would legally classify as a "breach of condition." This kind of breach entitles the innocent party (i.e., Van Halen) to terminate the contract. Of course, the contract itself can override this interpretation as it sees fit.
However, as noted by others, this is rather moot: someone who didn't notice this line in the contract probably didn't notice all the other (more serious!) issues.
Van Halen, at the time, were doing the largest stadium stage show ever. Most tours were 2 semi-trucks of speakers and lighting, VH were ~10+. Due to the never before done scale of the show rigging weight limits are critical. Not following it could lead to a stage collapse.
VH put the brown M&M’s in the middle of the weight requirement rider. This way the production crew could easily see if the local producer actually read the rider by seeing a bowl of brown M&M’s.
I 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.
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.