21–30 of 153 posts
I'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...
Earlier quoted context omitted.
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. [0]: https://www.snopes.com/fact-check/brown-out/
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.
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
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 m…
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 m…
No one reads manuals (unless they're written using our documentation tool) is the point here.
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.
Good writing avoids Internet memes and Reddit speak.
I'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...
What changed with Cat6?
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. 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...
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.