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.
you actually helped them? Hang up, charge your emergency hour consultant rates, and tell them you're available once they sign the agreement.
I'd rather be known as the guy who helps than the guy who is rude about consulting rates.
When people treat you that way, you politely say "If you want my help, change your tone."
If they don't, hang up.
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)
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.
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.
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.
Few people took any notice of it.
That nonsense would last exactly as much time as it took me to recognize the words and to hit "end call". The phone is for my convenience, not theirs.
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?
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.
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.
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?
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.
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.
Why not? Under what legal doctrine?
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 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.
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.
I think what people miss most in the “mainstream” narrative is honesty & truth.
Clickbait all the documentation! ;-)
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...
https://en.m.wikipedia.org/wiki/Goldfish#Cognitive_abilities
Same principle as rubber duck debugging.
> 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...
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 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.
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.
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...
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.
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.
(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.
Of course, you should probably have more canaries.
(If it does, then it seems like the lack of that information is itself information.)
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.
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.
Not sure if that would just piss off users beyond toleration, but it's an interesting idea.
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!
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.
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.
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.
(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).
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.
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.
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.
2018 https://news.ycombinator.com/item?id=18643258
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.
Still cool story with a good message though
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.
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.
