>Mistake 3: Communicating something one time is enough
I joined a company once where a particularly skilled engineer had become a manager. She was very good at her job and I'm fairly certain had something like 'perfect recollection'.
We were in a meeting and she went on about how she was upset people were doing a troubleshooting process wrong despite having sent out a detailed email.
Not wanting to do that thing wrong I searched my email, but couldn't find it. I asked about it and she told me "Oh it was before you joined us.".
I had been with that team for two years...
People tend to remember important things like it was yesterday, but don't always realize that other people can only absorb so many important things / don't always know how important it is... and email is kinda a terrible way to communicate it too. Let alone 2+ years earlier ;)
There’s some cognitive bias in which we assume that when we regard some information as important, that anyone exposed to that information will fully absorb it.
The reality is - while learning how to communicate well is hard, actually getting anyone to listen is many times harder.
I used to joke that in any meeting with more than 4 people, at any given time at least 1 person is day dreaming.
And since mobile phones and social media all this has got many times harder; attention spans are shorter and there’s a higher expectation that information should be somehow entertaining.
These days communicating something simple like an important date to 10+ people inside a company requires multi level marketing; email, calendar invite, Slack, face to face time ... use it all and still one of the 10 will somehow miss the message.
Interesting essay. Reminds me of some of the issues that come up in teaching. Even when you think you have explained something at the simplest possible level you are often missing background assumptions that seem to obvious to you that you can't even conceive of not knowing them
I’ve read that essay before and I re-read it just now and I still don’t understand what is meant by “avatars walking around on top of our company home page”. So I guess the essay proved its point.
> I used to joke that in any meeting with more than 4 people, at any given time at least 1 person is day dreaming.
This was a big problem with me in college. While going through proofs in a lecture, I would frequently have questions in my head and try to pursue them, and in 10 seconds I would have lost the line of reasoning of the proof.
For me, writing notes work to overcome that. If I write notes, I can keep focus longer. Plus, I would scribble all those questions on side and come to them later if they were not answered by something in lecture after.
It's alright if there the proof is sketched down somewhere, but I had a couple advanced courses where there were important concepts that weren't already written down anywhere.
> I used to joke that in any meeting with more than 4 people, at any given time at least 1 person is day dreaming.
This is my experience too. Based on this I concluded that 3 is the optimal number of participants in a meeting. Two would be having an active conversation the third one would be actively absorbing the content of that conversation chiming in once in a while. In fact even in a meeting with 6-8 people I noticed this pattern of 3. Just that members of this 3-clique would slowly change over the course of the meeting.
There's also the problem (for me, and I have observed for others) that emails sent to lists or large numbers of recipients/CCs automatically get less attention and priority than emails sent to me individually.
If I get an "all hands" type of group email, I skim it, or maybe just read the subject line, depending on who it's from. Over time I've learned that there's almost never anything directly actionable for me in these messages.
The day is too short and there's too much to do to spend time carefully reading long-winded broadcast messages.
If you miss a word in a conversation, you automatically fill it in. This is usually pretty reliable even with unfamiliar material, since if you follow standard grammar rules there's a decent amount of redundancy. Sometimes, though, this doesn't work. You think you were paying attention, but you missed parts and filled them in with what you wanted to hear.
Ideally there is a back and forth that checks that important information was correctly passed on. Failing that, some redundancy can make a big difference.
> I used to joke that in any meeting with more than 4 people, at any given time at least 1 person is day dreaming.
You don't even have to joke: you can put it in statistical context. If people day dream around 45 % of the time spent in meetings, and assuming that day dreaming time is distributed independently among meeting-goers, there's only a 0.55^5 = 5 % chance of nobody day dreaming at any given moment.
If you're willing to accept a lower p-value and go for an even money bet, people only need to day dream for 14 % of the meeting for you to win money in the long run.
Of course, in practise, day dreaming time is probably not independent: multiple people probably think of the same part of the meeting as dull.
> There’s some cognitive bias in which we assume that when we regard some information as important, that anyone exposed to that information will fully absorb it.
Part of the problem is that people get really upset when you don't assume that.
I’m always blown away when companies don’t have a knowledge base. Imo, if it’s not written down, shared with me, and told how important it is, then it’s your fault.
Email isn’t your knowledge base. Slack isn’t your knowledge base (unless you’re using a tool like Guru).
Use Notion, use Roam, shit even organized GDocs can work. There’s no excuse to not have things written down, maintained, and constantly shared.
I respectfully disagree to an extent. I think most/all documentation ends up rotting and being ignored. If you take the time to write it down, it doesn't mean that others will take the time to read it or refer to it.
I think it's better to just continually verbalize any "core values" with your team as you go day-to-day. Thinking that you've written it down inside of an organized GDocs is not much different than having sent it via email (the location to retrieve it just changes).
* What’s being written down isn’t valuable, so people don’t trust the wiki to have valuable information and therefore ignore it.
* What’s being written down is valuable, but people have been trained to get information elsewhere and therefore don’t bother going to the wiki
I don’t really know how to address the former (“write better!” isn’t very actionable advice), but in my work I see the latter a lot, and the only way you can fix it is socially—if someone asks you a question that’s answered in the wiki, you have to tell them “read the wiki” instead of giving them the answer yourself.
People are lazy, and it’s almost always easier in the short term to just ask someone for the answer instead of looking it up yourself.
If we get better search systems I would be totally on board. But most knowledge base systems have a hard time finding similes for words let alone sorting articles containing multiple keywords in a useful order.
Having the information written down is important if nothing else than a source of reasoning going forward (people tend to remember do X but rarely why in my experience). However saying that asking a coworker is a bad thing is giving way too much credit to the documentation.
Additionally if you are talking about anything but the most basic associations talking with people is a good thing anyway as you can discuss your idea and see if there are problems the documentation couldn't tell you about because said problem would be listed in a different place.
Sure, I should make clear: documentation/wikis are best for who/what/when/where of things like
- What permissions do I need to contribute code to this repo
- Where are the telemetry tables for X event
- Who’s the manager for project Y
- When will my commit make it into production
For the whys and hows that often warrant discussion, while I still think you should have basics documented (How do I add a new screen to this app, why do we call into this proxy service, etc) so that folks have a starting place, and then pursue actual discussion.
Even if the wikis are literally just the most basic associations, I still believe that would clear up a ton of repeated and honestly unproductive discussion time.
I've had a funny observation over the years. The more refined the wiki, the worse the code/ops are.
Good ops and code are usually to some extent self-documenting. If you had a wiki with 20 steps to perform some task, maybe the answer is that the process needs to be simplified.
I've noticed it a lot of times in legacy systems. There's often a page with 20 different idiosyncrasies that you have to deal with, and the code is too critical to update even with comments
This might be fine at a smaller company, but as you grow, having people verbalize these things results in slight variations that over time grow into very big inconsistencies.
Setting up MediaWiki and throwing it up on a Linode server costs 20 bucks a month and can be deployed from a Docker image in roughly 15-20 minutes. It can referenced by everyone, anyone can contribute to it with a full audit of changes, and it's easily searchable.
I use it to document technical and non-technical things like company policies, work flow processes, security practices, coding style, pretty much anything. New employees have a standardized on-boarding process that is clearly documented step by step for them to get setup with everything they need to start being productive by their second day of working here.
It's actually fairly low effort to do this and is a lot easier than having a bunch of people have to remember God knows what and when, or forgetting and then having to ask someone else who may have a vague recollection of it.
An authoritative source of knowledge that everyone has access to and anyone can contribute to is worth setting up.
I got really excited about the Linode/mediawiki solution. We're looking at Jira/Confluence right now, and it seems pretty heavyweight.
But then I remembered nothing takes 20 minutes. I'll bet it takes 20 minutes to set up the wikimedia server and then 4 days of Googling to get our single sign-on to work. We'll have to figure out what to do with backups. Plus we'll need to document the documentation process itself and do the painful change management with the organization. Finally, we don't use Linux, so it would probably take more than 20 minutes to figure this stuff out.
It's a great idea, but it's a non-trivial amount of work. Not that I disagree with your approach, but I'm saddened when I think about how to get there.
I do the same, even just for my own notes. That way it's all there, accessible, searchable, in the same place. Far better than everyone squirreling their own critical data away in a different tree-trunk.
Why would I want something like that on an external resource like a wiki? What's wrong with having it right there in the source in a README.md?
Easily searchable on my machine with grep or ack or whatever you use. Many tools (such as github, many IDEs etc.) open it up with when you open up the project, including formatting it. If you really want, you can serve it up somewhere via HTTP. When something changes I can commit it right with the changes I'm making.
This works for developers but excludes large swathes of other stakeholders, some with huge amounts of business/process knowledge. MediaWiki supports WYSIWYG via VisualEditor, which increases usage from others (and has the benefit of making tables much more pleasant to work with).
I completely agree with you for documentation that is not developer centric. A wiki and a WYSIWYG editor is the way to go there. Though it is funny to see PMs and other people fight with say the Confluence editor (that's what I'm stuck with at the moment @work and they've recently effed up the Jira editors as well in favour of non-developers). It's abysmal and since they changed it to remove proper wiki syntax editing I can't even really fix things for them easily and have to use workarounds myself instead of teaching them a little bit of wiki markup syntax from time to time or using it myself to fix things. It's like MS Word and everyone learning all the workarounds of how to undo weird formatting or fix documents. What was wrong with LaTeX? :)
That is absolutely not what we're talking about here though. If a project manager really wants to set up a local dev env for whatever reason, they can be my guest but don't expect me to tailor our whole everything around them and not my developers.
I assume you're referring specifically to the coding style document rather than the host of things that a company should document. The advantage of having the coding style documented in a format that supports some kind of markup over a plain text file is to support syntax highlighting, searching/indexing, cross referencing other documents, including diagrams and a host of other features that plain text files lack support for.
You should not assume and I should have specified more clearly.
Our code style is also committed. As spotless configuration files, eslint configuration files etc. You can run these locally if you want to. Our CI/CD definitely runs them and fails the build if it doesn't pass. No exceptions.
The README.md I am speaking of is actually more than one README.md. We have more generalized ones dealing with "This is how to set up your dev env, so you can actually develop stuff", to more module specific ones like "this module is special from everything else in X, Y and Z".
Documentation that ends up rotting and being ignored is usually a consequence of a poor organization/processes. Such places are usually not a very happy place to work at.
How exactly can you use an email (or email thread) buried somewhere as a part of onboarding process? How exactly can you improve that email when it shows as unclear/lacking info after you somehow managed to use it during onboarding?
1. It is easy to tell which documents are clearly marked as snapshots in time vs. living documents.
2. Most docs are snapshots, so people have enough energy to maintain the living documents.
3. There is a slack channel or team name on the living documents. That way, if you see something out-of-date and want to update it, you know where to ask.
from years of doing wiki documentation, document rot is fine, if it rots, so be it. Most of the time I write the docs for me but with a "getting started" frame of mind. On our wiki there are a whole bunch of actively maintained pages now that were initially seeded by myself or other devs, and there's a bunch of dead pages which are occasionally very useful , some of it is horribly dead. But the active pages are great, they save everyone time. Main thing is to not invest vast amounts of time to the docs, don't spend time drawing diagrams unless its a photo of a quick hand drawing, and just put in more effort as things prove useful
I think this is all cultural. Smart employees want to do good work. If you aren’t providing them with the context and knowledge to do that work, then you’re failing. If your documentation isn’t useful, that’s your fault. If no one cares about the roadmap and couldn’t even tell you what’s on it, that’s your fault.
It’s very rare you find an employee that’s purposefully malicious, at least in the early stages of a company (< 50 employees). Unless you have terrible character judgement.
If what you are writing down has value, and there’s no other way to obtain that knowledge, then people will use it.
Not really a general counterpoint, but I do think that if documentation is concise and useful enough so that stakeholders keep it up to date, it can work.
For example, I maintain a document that helps me keep track of bioinformatics files and some of their quirks (which files have two-line headers, etc). I do it for myself, but this information is also referred to by dozens of people in our group.
I agree with Tafster. I've been a consultant for 6 years and so I've seen dozens of knowledge bases and wikis. Some companies even have great processes to fill them in.
I have never, ever seen a company where those wikis are actually read.
One company I worked with had a very detailed weekly logging of changes, important things etc. The goal was to keep other teams informed of what each team was doing. It took many times many hours a week to keep it up to date. When they looked at the usage log, literally no one logged into to read the stuff except when going into to upload their part.
> Your attitude of "docs are useless" is self-fulfilling.
Yes. Of course the docs are horrible, if no one can take time to improve them, because improving them is not "real work". Spending one day fixing the wiki pages to make information easy to find, that's one wasted man-day! On the other hand, the whole team spending a few hours in meetings to clarify misunderstandings that would not happen if there was one clearly written wiki page about the topic... that's okay, because communication is important.
I think another problem is that things work bad by default whenever the "customer" is not in a position to give feedback and require improvement. Suppose the developer needs an information, and the wiki page is hard to understand. The developer is hardly in a position to request a rewrite from the author -- the author has more knowledge (about given topic) and therefore is in a stronger position. Also, the author may choose to explain verbally or in e-mail, and then the wiki remains unfixed.
Isn't a low read count fine in most cases? I wrote up some documents on setting up some apps in AWS. I expected those to be read maybe 2-4 times over their lifetime (and maybe some random browsing). There just aren't many people that should have to go through the steps.
Still a net time savings as those people won't have to reverse engineer things.
I totally agree with you, and disagree with the other two commenters here. I think this is a culture and communication difference in companies. I work for a distributed company, Automattic, and we use two tools for information which needs to remembered:
- p2, which is basically a live blog for long-form communication. Each team has one, and important conversations happen there. The informal saying goes, “p2 or it didn’t happen”. Long-form async communication is crucial for distributed work, and slack (or email for that matter) is a very poor tool for the job. (https://wordpress.com/p2/)
- a large wiki built on WordPress (e.g. it’s very easy for anyone to publish changes to it)
Both tools are used extensively at the company because everyone understands that real-time communication doesn’t last. I think the wiki gets a lot of traction because:
- it is integrated into our global search tool.
- People share wiki pages when someone asks a question. (E.g, someone asks me about $topic that I know a lot about, and I share with them the wiki document I already wrote about it.)
- Plus, these are linked to from p2 or slack as needed.
When I start trying to get historical context for something, I’ll use the global search tool and find anything ever written across p2 or the wiki site. That normally gives me a great start for what I’m working on.
I would argue that it is a cultural failing when companies don’t have effective communication and documentation habits. Is it habitual to write that wiki page when finishing your project? Is it habitual to have large, technical conversations in a publicly searchable environment? Is it habitual to summarize important conversations (in slack or from video meetings) on these more accessible tools? Is it normal for everyone to be commenting, editing, and participating? These are all normal for me, and I think a big aspect of that is the existing company culture. (And obviously the tools make it very easy to do.)
I totally agree with you, and disagree with the other two commenters here. I think this is a culture and communication difference in companies.
It definitely is a cultural thing. For example at my present company no-one reads wikis, or email, or chat logs, or even error messages, because that is perceived as "low status" activity. High-status people give a vague idea of the problem then sit back and watch minions scurry about trying to figure it out. The problem is that this senior-manager example is now being emulated at even the lowest levels, so there's no-one left to actually do it.
I've seem some larger projects at bigger organizations where extensive wikis were available. I'm pretty sure updating docs/wikis was part of the "definition of done" on a task. Problem was, most of the devs were terrible, terrible writers. There was little to no consideration made for "explain this as if I don't already understand it" on these pages. They were dry, full of useless generated ERDs and other generated filler, and generally I'd end up reading the source code or reading the integration tests to get a better sense of what was going on.
All in all, I actually agree with you. Knowledge bases are great when done right. But it takes time and a general knack for writing, and that's not something that most devs have from my experience.
We ought to work harder at teaching writing. I think there's a definite group of people that really _love_ writing, have a general knack for it and work hard to turn that knack into a talent. But, those folks aside, I've found there's simple tweaks that can be made to most technical writing that greatly improve it. For example, in code documentation explain "why" and not "how". Later source readers will probably be able to understand your code unless it's especially complicated but they will not, from the code, be able to figure out why it exists. Lots of folks write the "how" down though, in part because the external context is taken as a given in the moment -- they're very familiar with it right then and there -- but also because the "how" is probably more interesting than the "why". Empathy for the ignorant is something you see in excellent technical writing, less so in the middling stuff.
> Imo, if it’s not written down, shared with me, and told how important it is, then it’s your fault.
This is no opinion. It's spot on truth. Human Comms Rule #1 - The clarity of the communication is the responsibility of the sender, not the receiver.
The last company I worked at, had a weekly Friday team meeting where major announcements were most often made. More than once, I took a Fri PTO - often prior to a Monday holiday - and never did anyone say "You missed important X and Y on Friday." Instead it would come up later with an air of being common knowledge. Maybe it was, but not to me.
I got tired of the amateur approach to comms and eventually left.
> I’m always blown away when companies don’t have a knowledge base.
The company I work for has at least 5 that are relevant to any single employee... as far I am aware of. That is, I'm not counting different departmental knowledge-based for different departmens or anything like that. I learned about the 5th more than a year after I joined the company, and I haven't changed positions either.
Naturally, when they teach you things as a newbie, half of the information is not on any of the 5; and if you go rummaging through them you'll find a lot of gems - but also a of conflicting, confusing, and/or outdated information (often kept up-to-date in a useless sense and thus dated recently).
Slack is definitely a good enough knowledgebase for problems with your environment setup and other transient things. We have a channel that all the devs are on and if someone has a problem with their setup they usually ask there. Since all of this stuff is sort of changing all the time or new problems come up (say because of OS updates or toolchain updates), writing it all down in a knowledgebase is sort of wasted energy and time if you ask me. Slack search is good enough.
And I don't think that it's about whether its written down either but more about people not remembering stuff and not knowing that search exists... We literally had a case last week, where a guy was reporting an issue on there and I was like "wait, that problem happened like 3 or 4 times in the last couple week", so I searched slack, found it right away and sent him a link to the thread, which had a solution to the problem. Turns out, it was actually _the same guy_ with the same problem!
Please tell me how a "knowledgebase" would've helped him?
(and yes we do have docs for the general "this is how you setup your dev env from 0" right in our source repo.
> wait, that problem happened like 3 or 4 times in the last couple week
I don’t disagree that Slack _can_ be a knowledge base, but it’s not by default. For something like you mentioned, and I’m not kidding, I would have immediately written it down in a doc for environment troubleshooting. Something like Guru can actually help you do this automatically in Slack. That way you can add it to your existing knowledge base. This helps employees transition from “hey let me ask Bob” to “hey I’ll just check the wiki”. When the default is to check the docs, instead of asking “Bob” you know you’re on the right track.
Funny you mention that. We do have Stackoverflow (check it out if you like this sort of thing. You can have your own private section basically) but I personally don't find it useful. We basically only use it like a troubleshooting section to document longer lasting information.
For proper persistent documentation we have README.mds in the source code. For transient problems (like the above, it's actually something buggy in our code but nobody has been able to figure it out yet), there's slack and I don't think it warrants spending time to write it down somewhere else. Let's say you are a SaaS company with one product. You use kubernetes. Let's say one day you have a problem with minikube on your dev machine because of an OS upgrade (say MacOS Big Sur effs something up). Does it make sense to document this specifically somewhere (takes time i.e. money) vs. the next time someone upgrades their machine they search slack for the error message that someone posted, figure out all they need to do is upgrade their minikube version. After some time, all your devs have upgraded to Big Sur and upgraded. The information will automatically age out of slack.
I find this is actually pretty neat and the most efficient way of doing it. Especially because 90% if not more of your developers will always "ask Bob" before searching anyway, so putting effort into the wiki (or any other doc) is wasted effort anyhow. That's because sending them a link to an old slack convo vs. the wiki or an SO thread or whatever you use is really not that different.
The cost of documentation is far larger than its creation though. I agree stuff needs to be captured, but it also needs to be maintained and promoted, otherwise call it by what it really is, sharepoint.
Not to be contrarian, because you’re not wrong, but to provide a little additional flavor... I don’t have anything close to perfect recollection but I do have good attention to detail and how problems intersect, and a career-long recognition for it.
I’ve found myself repeatedly in a position similar to the one you describe for your former teammate but where I’d been regurgitating the same information for anyone who’d listen for months on end, often multiple times a day. I was on the newer end of the spectrum so I couldn’t imagine it being brand new information to anyone.
But I had to repeat the same details, including how they related to other recurring problems, for months before I could get any kind of shared understanding of the general problem. And even when I achieved that it would flit out of existence at the presence of any new shiny thing, even as I tried to butt in and explain how the problem was known and how I knew it related to the underlying problem.
People just don’t listen. They might want to. They might even embrace it. But unless they’re targeting the problem you’re trying to raise awareness about it’s all too easy to treat something as novel and all too easy to dismiss a repetitive voice.
People can only listen so much too. Like if you go over 6 critical issues at a meeting once or more times a week.... how many issues can you really 'know' / remember.
And when you're troubleshooting all those symptoms rarely just present themselves just like the examples and so forth.
After the fact it is easy to match and say 'this is just like that' but that's miles away from trying to do that every step of the way as something develops.
Well in the case I was describing it was just the same symptoms recurring. The reason they recurred so long is that the people who weren’t listening were focused on the symptoms and ignoring the root cause.
I wish everyone would treat email as the temporal medium it is.
It's fine to use email to announce for example that a new procedure/policy exists, but if it's not posted in some canonical location (where the latest copy will always be found) it might as well not exist. Email is where your keystrokes go to die.
Just the other day I asked about something and was forwarded a document titled ".... FINAL-v2 (July 2017)". I can't tell you how much that enrages me.
The problem with email is that it ported letter writing culture to the internet. A big internal announcement at my company can take days to write and undergoes multiple rounds of review.
Once people have put in that effort they aren’t going to bother redoing the effort for another medium. Meeting notes are the same way.
This reminds me of my last job. There were some instances where two teams would work on the same feature. The team leads and devs would regularly get together to make sure that we were on the same page in terms of who was developing what and what the specifics of the design were. It worked well.
However, management would sometimes feel the need to bring in a developer from neither team who was supposed to facilitate development, I believe to cut down on meetings (because developer meetings that weren't standups, retros, or refinements were bad, apparently). What ended up happening is that this dev would have a meeting with Team A, get the details about the project, then go to Team B and talk about the implementation. Team B would have another idea for how the development should go, so the median dev would agree that the plans would change. That dev would not write down any of the details, let alone communicate back to Team A about Team B's changes. It caused a lot of unnecessary friction and wasted time. Management pretended like this wasn't something that could be avoided.
So long story short (and also to your point): communicating once isn't enough, but not communicating at all is unacceptable
I recently joined a great team that has lots of different services that do things.
Some people explain to you how things using names of things you don't know about, they don't realize that telling me and then we get "info from dragon" means nothing to me.
I joined a company once where a particularly skilled engineer had become a manager. She was very good at her job and I'm fairly certain had something like 'perfect recollection'.
We were in a meeting and she went on about how she was upset people were doing a troubleshooting process wrong despite having sent out a detailed email.
Not wanting to do that thing wrong I searched my email, but couldn't find it. I asked about it and she told me "Oh it was before you joined us.".
I had been with that team for two years...
People tend to remember important things like it was yesterday, but don't always realize that other people can only absorb so many important things / don't always know how important it is... and email is kinda a terrible way to communicate it too. Let alone 2+ years earlier ;)