8 ms·

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 fa

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.

cm2012 6y ago
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.
- etothepii 6y ago
  > I have never, ever seen a company where those wikis are actually read. 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.
- antonvs 6y ago
  > I have never, ever seen a company where those wikis are actually read. 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.
  - afarrell 6y ago
    > Docs are only useless in companies that actively want them to be useless. Like most things in life, it takes active effort of ongoing maintenance. https://www.edge.org/response-detail/27023 https://www.edge.org/response-detail/27023
  - Viliam1234 6y ago
    > 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.
- nitwit005 6y ago
  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.
taftster 6y ago
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).
- carbocation 6y ago
  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.
- Kranar 6y ago
  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.
  - tharkun__ 6y ago
    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.
noahtallen 6y ago
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/ 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.)
- goatinaboat 6y ago
  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.
einpoklum 6y ago
> 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).
tharkun__ 6y ago
Well yes but no if you ask me. 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.
- ryanSrich 6y ago
  > 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.
  - tharkun__ 6y ago
    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.
chiefalchemist 6y ago
> 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.
adverbly 6y ago
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.
- troutwine 6y ago
  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.
  - bollu 6y ago
    Do you have more on how to get better at writing?
deleted 6y ago
[deleted]
skeeter2020 6y ago
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.

cm2012 6y ago

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.

etothepii 6y ago
> I have never, ever seen a company where those wikis are actually read. 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.
antonvs 6y ago
> I have never, ever seen a company where those wikis are actually read. 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.
- afarrell 6y ago
  > Docs are only useless in companies that actively want them to be useless. Like most things in life, it takes active effort of ongoing maintenance. https://www.edge.org/response-detail/27023 https://www.edge.org/response-detail/27023
- Viliam1234 6y ago
  > 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.
nitwit005 6y ago
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.

taftster 6y ago

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).

carbocation 6y ago
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.
Kranar 6y ago
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.
- tharkun__ 6y ago
  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.

noahtallen 6y ago

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/ 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.)

goatinaboat 6y ago
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.

einpoklum 6y ago

> 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).

tharkun__ 6y ago

Well yes but no if you ask me. 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.

ryanSrich 6y ago
> 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.
- tharkun__ 6y ago
  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.

chiefalchemist 6y ago

> 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.

adverbly 6y ago

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.

troutwine 6y ago
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.
- bollu 6y ago
  Do you have more on how to get better at writing?

deleted 6y ago

[deleted]

skeeter2020 6y ago

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.