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 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).
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.
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.
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.
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".
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.
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.
* 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.
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.
- 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.
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.
This is a choice, not a fundamental law.
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.
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.
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.
The problem with documentation is that it is the making of it that creates most of the value. Like so many things the value looks like duplication.
This misses a key point.
When I get a query that's answered by something on the wiki, I reply with a link to the wiki.
If the wiki link isn't fully relevant, if possible I update it before replying.
If I have to write significant new content to respond to the query, I create a wiki page.
Your attitude of "docs are useless" is self-fulfilling.
Docs are only useless in companies that actively want them to be useless. And those companies are, with no exceptions, seriously dysfunctional.
Like most things in life, it takes active effort of ongoing maintenance.
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.
Still a net time savings as those people won't have to reverse engineer things.
- 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.)
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.
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.
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.
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.
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.
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.