Doesn't need to be exhaustive docs - usually just a high- to medium-level explanation of what why and how goes a long way.
Controversial/surprising/confusing choices should be documented in several places - e.g. in the readme, in a bug/ticket, in the check-in comments and also a comment in the code referencing the readme/bug/ticket for more info.
Over-communicating the confusing/surprising stuff helps a lot and helps to prevent the "what the hell is this crap? Let's rewrite it" issues since there is a long paper-trail explaining why things were done that way. Putting code comments referencing bugs/tickets etc (ideally with clickable links direct to Jira or whatever - e.g. "// This does <surprising/confusing thing> - see the discussion in http://bug tracker/12345678" ) means that the trail starts right there in the code, and people have not had to trawl through some nonsense wiki to find the hidden nugget of info (let's face it - we'll read code but hardly ever go out of our way to find and read wikis etc first)
I also write comments first when writing complex code and then fill in the code in between. More than once this helped more than any documentation could, because people do not read documentation if they can avoid it, and avoid it they'll try.
Markdown is fine until you realize you would like to have figures, images and tables.
I don't want to spend my time over trite details of a text based markup when I could spend it actually productively.
At that point it's way over easier to use a text processing document of choice (word or open office). I say this as a enthusiast of text based markups over decades from Latex to Markdown.
You can't have images in source, but if you really need it you could add an ascii-art-style table. There are tools to generate these, such as https://ozh.github.io/ascii-tables/
If a hand typed ascii graphic does not suffice for code comment embedded docs, then it would be better to include separate docs altogether.
"Everyone" is not using LaTeX.
This Friday I had spent about 15 minutes trying to put an editor cursor within an empty code block in Confluence. Is that a joke? Do you know how I fixed that? I copied a non-empty block from another paragraph and then edited it.
It would take me or someone else half a second to do that in Markdown/Wiki/LaTeX.
It's totally acceptable Confluence at least tries to provide a non-programmer friendly interface for the domain experts who are not necessarily programmers. But it's not acceptable if the gui is broken...
And from merge conflicts.
Markdown is great, but I’ve seen so much time wasted on Rube Goldberg solutions that would be trivially addressed by using less cool solutions like Word or GDocs.
If you need something more complicated than markdown can provide (depending on your renderer, that could something as trivial as line breaks inside the cells of a table), then it’s obviously not going work. But for any solution that’s great in one use case, there’ll be others where it’s completely impractical.
At the risk of just mirroring my comment above:
Low-level nuts-and-bolts documentation can't be accessible to non-technical people, by nature. Documentation of high-level designs are another matter. Why not use a wiki for the documentation of high-level decision-decisions? A wiki can be accessible to non-technical staff, and it's trivial to link to a wiki page from a comment in source.
It also keeps the source tighter. It negatively impacts readability if the source is full of non-vital comments.
Because if you create different solutions to meet the publishing preferences of different groups inside the organisation, then I don’t think you’re meeting the goal of institutionalizing the knowledge. If a consumer wants to find some documentation, you don’t what their first step to be trying to find the system it’s stored in. Especially in very large organisations, where you could easily end up operating quite a few different publishing platforms.
SharePoint is the closest things I’ve seen to a one-size-fits-all solution. But SharePoint is rather terrible to use.
High-level project descriptions don't belong in code. It's a different beast, and doesn't belong in the repo alongside the implementation. Non-technical users probably shouldn't even have repo access.
In-code comments, on the other hand, can't reside anywhere else.
> If a consumer wants to find some documentation, you don’t what their first step to be trying to find the system it’s stored in.
They don't need to look. That's what hyperlinks are for.
I'm not sure if you mean end-user here, or the consumer of a library.
If an end-user wants documentation, that means it's high-level documentation, not nuts-and-bolts documentation on the workings of code. A wiki is a fine solution for this. A non-technical end-user has no business exploring the repo.
If it's someone looking into how to use your library, the distinction is still there. If I want to know what Qt is, I look it up on Wikipedia. If I want to learn about a specific concept, I look for a documentation page like this [0]. In neither case would source-code comments be a reasonable choice.
> Especially in very large organisations, where you could easily end up operating quite a few different publishing platforms.
Maintaining a stable intranet wiki is no great challenge.
> SharePoint is the closest things I’ve seen to a one-size-fits-all solution. But SharePoint is rather terrible to use.
For UI reasons I'd go with a wiki over SharePoint, but they're similar in principle: documentation lives in the intranet, each document has a URL, and documents are mutable. They can coexist if they need to: use hyperlinks.
I'm not sure a one-size-fits-all solution is a good idea in the first place. A legal document about a project is going to end up as a .pdf, and doesn't belong on a wiki. On the other hand, technical documentation like [0] should be handled in a 'web-first' way, such as with a wiki.
Perhaps if SharePoint's document-editing were more like a plain old wiki, I could be convinced that it's a reasonable one-size-fits-all solution. (Although in a sense it's doing several things.)
That's just, like, your opinion, MaxBarraclough. If they aren't in the repo, they're never going to get updated, and as a result they will be outdated within 6 months on any project that's moving anywhere. I prioritize freshness of documentation against most other attributes. It does nobody any good to have documentation for the system as it was 2 years ago.
> If they aren't in the repo, they're never going to get updated
Not so. The Qt folks use a separate repo for their documentation. [0]
My point earlier was that high-level documentation is a separate project than the implementation. You could keep the high-level documentation documents in the same repo as the implementation if you want, that's just a monorepo.
This ignores hyperlinks. Why not use in-code comments for explaining nuts-and-bolts matters (for example, to explain strange-looking platform-sensitive code using #ifdef), and use links to wiki pages for descriptions of high-level design decisions?
All of this applies uniformly for the code I write for others, as well as code I write for myself.
A way to measure people's contributions could be counting how many times those lines in the wiki were copy pasted to solve problems, but in general it's not easy. We could count commits to markdown but as in code, two lines could be worth more than one hundred.
As for tracking commits, if the metric becomes a goal it becomes useless. People will game the system to have more commits, or worse, write a bot to break up their contributions into as many commits as they can get away with.
One line can indeed be worth more than 100 if the line fixes helps fix some production bug. The biggest issue I have is people fixing things and not documenting the fix.
Our metric of "success" for our shared knowledge is how many people outside of our company/org find our stuff useful. But this is not always possible in secretive or highly competitive industries.
Kathy Sierra said "out teach your competitors". https://youtu.be/Dsryx3Ra5pU I totally agree with this mindset. https://headrush.typepad.com/creating_passionate_users/2005/...
That does tend to be a great help if people follow it. One problem though: We're on our 3rd tracker since I started at my job. Lots of knowledge in those old cases disappeared because of it.
This is the only clearcut rule that I can think of that is obvious and non-negotiable.
Other things of course make sense (document something in code, other things somewhere else) but are more matters of taste and culture.
(public examples are the Angular Commit Message Conventions or the way saltstack uses that stuff https://github.com/saltstack-formulas/.github/blob/master/CO... - you basically enforce some rules using commitlint and record logs using semver, even if you end up not using the versioning for your software)
HashiCorp produces a mind boggling amount of prose (non-code text). Every employee can read every RFC going back to the first sketch of terraform which was completely rewritten in a second revision. Mailing lists are alive and well. PR descriptions and discussions are often longer than the code being changed.
No other company I've worked at has had this dedication to recording decisions, and all of them have struggled heavily with losing institutional knowledge. HashiCorp isn't perfect, but I want all future employers to at least pretend they're remote-first as that seems to be the forcing function for writing everything down.
Update: while writing skills are helpful they're definitely secondary to just ensuring knowledge is splatted down somewhere in some form. Perfect is absolutely the enemy of good enough, and I'd rather struggle to gleen knowledge from an unformatted readme in a deep dark corner than have nothing at all.
If you’re working with people who don’t agree with that process, just leave. That engineering culture is bad and you’re not going to get anywhere. People will use the empty excuse that careful design docs slow them down too much to convert it into a political debate, and try to make the burden of proof on the person asking for alignment prior to resource committal, burying _you_ in bureaucratic doc writing to avoid writing self-evidently more appropriate design docs themselves.
The idea of changing this kind of culture is a fantasy and you’ll just burn yourself out. Just leave and don’t work for places like that. Don’t hire people like that.
- Fear to go on vacation or take sick days because you'll miss live decision making
- Paternity/Maternity or other extended leave requiring a second onboarding upon return
- Animosity when left out of a lunch or beer where a design was discussed or decision was made
- Cabals of knowledge holders weaponizing their knowledge for job security or advancement
- Onboarding is a huge drain on existing workers as all knowledge must be shared 1:1 synchronously. Discourages team growth.
- Bias toward risk takers and the loudest voices. Difficult for thorough and thoughtful team members to be effective.
If none of these things apply to you, great! I don't want to presume there's one best way of operating.
I haven't looked at it myself, but I know Google just released some training materials for technical writing: https://developers.google.com/tech-writing
The biggest immediate benefit during onboarding. A new hire can review all the broken paths that have already been tried. Second related benefit is existing employees can go back and look up the details on what was tried and why it didn't work. A prior broken solution may become feasible as assumptions/business/etc... change.
Calling a meeting anyway is great! You have a document to reference to guide the meeting, answer questions, and scribe discussions/decisions! If your worst case scenario is that your technical document becomes a glorified meeting agenda, that's not so bad.
Also remember that documents live ~forever, so even if you get no immediate response: write for your replacement 5 years from now who has to figure out wtf you were thinking. :)
Starting a set of services should be as simple as "docker-compose up", building should be as simple as "make", checking out the code should be as simple as "git clone", etc. You shouldn't need a shitload of wiki checklists that describe how to install dependencies and how to check out all the git-directories with correct versions relative to each other. Save your wiki for high level documentation
A must for this to work is to avoid configuration state in your servers that is not captured in your source tree. This is the most critical because it's easy to forget and it can quickly become a blocker, not just for RnD but also ops. You have this super important service that everybody depends on and it always works, suddenly the server burns while go-to-guy is on vacation and nobody knows how to bring it up again from a clean slate because it involves several hours of clicking around in some proprietary GUI and ticking all the correct boxes. If you can't reproduce this service today, make a VM snapshot already, then start work on fully declarative service configuration.
In practice... Well, the initial question was about good practices so perhaps we shouldn't lift the lid on bitter experience.
If non-tech people on a team need to understand, in detail, a technical process, I think it’s easier to teach them to read through a script than to pay a tech writer to document the script, all the time.
I’ve run into this problem with non-technical project managers who want to understand in detail. If this level of understanding is necessary then it’s possible to scan a source file to read comments.
Or generate documentation from source and dump it on a web server somewhere.
Although lately even non-technical people are able to read and edit markdown files on GitHub.
Obviously additional documentation would be great, but code itself is a minimal type of documentation.
My point was that by simply automating the process you don't institutionalize the knowledge as much as you move at least part of the problem somewhere else.
It heavily depends on the application, though. In my domain the implementation is rarely self-documenting, and most of the system's complexity is usually baked into the spec or the human part of the process. In some other domains the proportion is completely different.
Firstly, it fails to solve the problem of actually capturing knowledge. In fact, if anything, you're suggesting that knowledge of the systems and processes shouldn't be necessary in order for the business to function and that building a black box that "just works" is good enough. The problem with that is two-fold. First, using code to capture knowledge (eg "read the makefile to see how it works") fails to capture any reasoning for decisions that have been made, and secondly any history of the changes to the system are lost if you do ever decide to wipe out the git history of the repo (eg a shallow clone, or a squash, etc). Those may or may not be important to you but I've found it useful in the past.
Secondly, there are non-functional requirements for things that can't really be captured in code. For example, "The system relies on an external service that can only be rebooted by calling 555-1234" is knowledge that no amount of single start up command automation can fix if there's a problem. That needs to be in a recovery policy document so everyone knows where to look if the system fails. That way the document can be reviewed by non-technical people as well which is a huge bonus.
2. Common, easily searchable place to put all documentation at. Good search capability is critical. Wiki is ok.
3. A good code & commit search engine. Ability to search code reliably obviates the need for a lot of documentation.
4. Weekly knowledge sharing sessions with the whole team. Both presenters and question askers need to be rewarded to keep engagement.
It is like replication in distributed systems. There are varying levels of redundancy you can get, and each higher levels involves higher overhead than the previous, so there is no golden rule - it needs to evolve as the organization evolves. A startup might have many people who are the only people who know certain things, but a 10000-person company surely should not have any institutional knowledge bound to one person.
I have mixed feelings around documentation because I can often read the code faster than the docs, and docs are often incomplete, inaccurate, and out-of-date. Docs for truly long-lived things are nice, though.
As for good search, that's easier said than done. The heuristics Google used for search don't work in code, and searches are too rare to do useful ML for relevancy.
Edit: seeing the downvotes...
I don't actually mind writing documentation, but more often than not, I've found people like(?) writing it because it makes them feel like they're improving the situation by doing something. I'd rather the effort be spent on better naming and factoring in code. Docs are also very prone to rot and drift.
That said, I've found Java docs, MDN, and most man pages to be very good, in part because of how thought-out the docs are and how static the interface is. I'm also a fan of docs that bootstrap new developers. Someone else said they like docs describing "principles," and I like that idea--guidance so you know what A should do vs. what B should do.
The problem I have everytime time I read or hear this statement, is that code is excellent in telling "what" happens, but often very opaque in "why" it's done like that. If the why isn't clear, code might be changed/refactored and stuff breaks, because the developer didn't understand the reasons behind the apparent code smell. It's comparable to Chesterton's Fence [1].
I much rather have some additional documentation than "self-documenting code" that does (apparently) weird things and tells me nothing about the reasons. Also outdated documentation can be helpful, when it's version controlled. That gives you context how the code evolved and if it doesn't state it directly at least pointers why the code is like it is now. That's also why I mostly prefer in code documentation to Confluence/wiki documentation, because the time/change relationship between code and wiki is much harder to comprehend.
[1] https://en.m.wikipedia.org/wiki/Wikipedia:Chesterton%27s_fen...
- unit tests show how well the developer understood the requirements at the time they wrote the code - git commit history shows who and when something changed (probably assuming history not rewritten :) ) - git history can be more informative, if and it is a big if, the developers write enough information and not just “changed code” type comments - in-line comments are for “why” - explaining things that look odd or go against standards or best practices, or “I’m doing this now like this, when x is available use that” - notes to help you and others - wiki is for higher level “why” to help people understand the code, where there is a lot of complexity I really like the idea of a “book of the xx” like the book of the runtime here: https://www.hanselman.com/blog/TheBookOfTheRuntimeTheInterna...
There can and will be several services/apps working together, external services required for some stuff, different set of configurations for different environments, CI/CD, software packaging, etc...
How we deal with it where I work - service developers/owners are responsible for providing docs for their services. Ops provide infra/CI/deployment/high level 'how all this works together' docs. Everything that can be code, should be code - with it's documentation. Of course there's issue tracker, wiki, commit messages all tied together using issue tracker IDs, etc.
And it still takes time for new people to get their heads around the 'how everything is working together'. Amount of docs we're writing is significant. Some of the docs is auto generated. Time for docs keeping is accounted for at estimating the time required for developing new features. Being a member of a remote team I can't imagine how we could be able to work otherwise.
Some people just work better on their own.
IMO, what's worse are "knowledge hoarders". Usually they've been in the company for a long time and they maintain their position by being as stingy as possible with their knowledge. You usually find these people in big orgs, and they can be quite toxic.
They also don't write good documentation.
Strongly disagree, been there, hurt like hell. Solo people on projects mean that other people can't give meaningful reviews (because they don't know the project that well, and because they have their own work), leading to 1. developer not getting good feedback and improving, 2. higher risk of them going down some rabbit holes, 3. bus factor of one and stressful vacations, 4. less guarantee that the docs and the code are any good, 5. a danger that this solo developer will turn into one of those "knowledge hoarders".
Solo development is never OK (imnsho). Sometimes you can't avoid it, but it should be a calculated risk, and only a temporary one.
What would you say, in a team of 6 devs, if a pm just walked up and said "If we can get 6 different tasks done in a week versus 3, guess which one I'm gonna pick?"
It is pretty common in the embedded world in smaller companies. There just aren't enough developers to render enough support.
The problem with one-man-shows is the dependability. A lot of web developers go that route. But if they are unavailable because of private stuff or illness, the project they are working on is basically iced.
The way I like to measure this is there should be more writing than programming going on within the company. Some investigations, research efforts, or designs will lead to nothing, however every implementation should come with research, design, and retrospective documentation. In that case there will always be at least as many written artifacts as programs.
The way to prevent the nightmare of an illiterate workforce with only oral history is to hire people who can write and practice documentation-driven development, instead of hiring people who can memorize leetcode trivia.
Two weeks of paid vacation where the company isn't allowed to email them or call them for help: I guarantee that documentation practices will increase substantially.
And by innovative I mean “we have no idea how anything works - let’s fix it.”
What is the equivalent of weight decay?
throwing off 75% of knowledge increases generalization capabilities
(actual experience detecting real criminal behaviors within financial claims)
We didn't write any documentation or have any internal wiki or anything like that, and everything seemed fine.
I also find it pretty questionable that someone couldn't write a computer program that can embezzle unattended for two weeks. You don't use your own credentials, you stick it in some other program and have it use the logged-in user's credentials. Are you auditing your HR system before you log in, and are you sure that the "ls" you're invoking is the same "ls" that actually came from Debian? No? Then it all seems very pointless to me.
Having worked in Middle Office before being promoted to the Front, he had a really good knowledge of how operations and risk management worked in the bank (plus some still working write accesses to specific systems) which allowed him to mask his very large positions with fake opposite trades that he was putting in every day before the nightly risk snapshot and cancelling before they could be confirmed.
The guy basically did not take any holidays in two years - otherwise his large positions would have appeared on Risk radar pretty quickly...
If you are into those stories and want much more details than my poor summary I really recommend reading the SocGen post-mortem investigation.
Disclaimer: I worked at Société Générale during the Kerviel era - also there is a lot of controversy in France about how much the bank knew and let things happen (Kerviel was making a lot of profits - until he wasn’t) and if that was used to cover subprime related loss - this post does not represent an opinion on this case!
If you are a sociopath who knows programming (more and more people in finance do every year) and is in finance (two fields with more sociopaths than some, perhaps), then why would you leave money on the table? You are already morally bankrupt and know how you would get caught, and therefore how to not be caught, and know that this money is going to you with zero issue.
Just evidence that documentation != institutional knowledge. It's not actionable knowledge if no one reads it.
When someone is on leave who has specific knowledge, this is just planned into the sprint. As in "xxx knows most about this feature, so let's wait for him to return".
Even when we do write documentation it just gets lost, or developers don't bother looking anything up.
At least in my team, is see:
- Managers allowing people to only take on specific work, therefore people are becoming highly specialised
- Individual developers don't push others to write documentation, instead they wait until somehow they have to do a task, spend 2 weeks to figure it out, and then write some documentation around it
- Individual developers who force themselves to only work on specific pieces. (I think mostly to fuel their ego so they're needed)
- The company not encouraging knowledge sharing, or simply not providing good tools for it
- Product owners who don't really care about the product
In such context a process becomes a (written) 'procedure/specification', and some folks stop innovating, they just do it "by the book".
HR quickly grasps this and hires people with less and less skill, cheap personnel 'just able to apply to procedures'. Other ones feel like cogs in the machine (especially the best ones, hunted by competitors) and quit.
Someone departing with the 'procedures' may let a competitor obtain a rather complete grasp of it and adopt the best bits.
Letting each team decide about this and establish cross training seems preferable to me, and has many other benefits.
If we find a better way to do something then we make a new video.
There's a team member who transcribes videos into google docs for people who like to read and search in google drive.
It's pretty simple and it works wonders for an international team.
However it is often essential to have an alternative form (eg transcription or at least summary of steps) simply because of discoverability - even with brief screencasts it can be awkward finding the content otherwise.
I see a lot of responses here automatically assuming that capturing institutional knowledge is about code, but there's so much more of business processes than code that needs to be captured, even in a tech rich environment.
In companies I've worked at large and small, the most important information just comes from people's memories ("oh yeah because we decided X in that one meeting six months ago, remember?").
And then once a critical number of people leave the team/company, so much time is wasted reinventing and rediscovering things.
The only solution would be for everything (every meeting and decision) to be rigorously documented with outcomes and justifications, and for every new team member to go back and read the entire history to get up to speed.
But 90% of people seem to detest writing and/or are terrible at it, and it takes up a lot of time. And new hires are never given the time it would take to read the whole history anyways -- they're excited to start working and the team needs to start showing extra productivity ASAP. So for both reasons, it basically never happens.
So you just hope that the rate of gradual knowledge osmosis from old members to new members is faster than the rate of turnover. And when it isn't, you just accept that your team's ability to deliver profitable features will slow down drastically. And at least for the critical business logic in your product, you mostly rely on tests to make sure at least things don't break when a new team member starts changing things.
It sucks.
Action focussed minutes?
What I’ve often done is asked new hires to document what they discover. New people are easier to mould to a new behaviour and often have the questions you need to know. When documenting becomes the habit, more people do it. Current 500-person company is very good at documenting many aspects, because we’ve done it since year 1.
- Follow these steps.
- If anything is unclear or doesn't work, update it.
You can do this as a wiki page or a Google Doc. The important thing is that the answer to the question "where's the documentation for X" should ALWAYS be "it's in the doc-of-docs".
Then you can take it a step further: you can say "it's in the doc-of-docs... and if it isn't, when you find it, add it to the doc-of-docs!"
It's a universal truth that documentation for projects and teams ends up scattered in many different places. A doc-of-docs is a lightweight technique that can really help here.
My company has basically everything on Notion and any time someone asks a question more than once, it gets added
Three Docs for the Product-kings under the sky, Seven for the Dev-lords in their halls of stone, Nine for Mortal Men doomed to die, One for the Dark Lord on his dark throne In the Land of Mordor where the Shadows lie. One Doc to link them all, One Doc to find them, One Doc to bring them all, and in the darkness bind them, In the Land of Mordor where the Shadows lie.
My goal was to introduce a culture of internal blogging at the company. I didn't really succeed on that front - I used my blog a bunch and a few people made a post or two - but I like to hope that if I'd kept at it for longer (I left the company) it would have started to catch on.
The reason I like internal blogs is that they release you from a lot of the pressure of writing more formal documentation. If there's a technique that I think is a good idea but that has not been established as an agreed best practice, writing it up in official documentation doesn't feel like the right thing to do. Writing it up on a personal internal blog as "as-of date X my opinion is that we should do Y" is always OK.
Likewise: writing documentation that later goes out of date can cause harm. Writing a blog entry that says "as of February 2020 this particular system worked in this particular way" seems much safer to me.
I guess the 1% rule [1] applies to internal systems as well...
[1]: https://en.wikipedia.org/wiki/1%25_rule_(Internet_culture)
In retrospect one of the main reasons for the failure was social rather than technical. The engineers designing things saw recording the rationale as just an extra job that had to do, with no immediate benefit to them. If anything, they saw it as opening them up to more scrutiny and increasing the chance of their job being outsourced in future. So keep that in mind.
I would invest in that if your are in a complicated or specialized domain where it takes months or years for someone to really get their mind around it. One thing I have noticed is that private work environments tend to be present at the low turnover environments I've seen. At least a cubicle.
Another option is extending low hour contracts to departing employees as sort of an off-ramp to their role. They are on a few hours a week or as-needed to handle the dwindling number of cases where they are most needed.
* If they're good at documenting, and willing to, task them to do as much of that as possible. The documenting might be in adding code comments and API docs, writing separate text files, etc. The person might not be able to document off-the-cuff, but have to work through a topic slowly, such as going through and re-understanding some old code themselves, going through a manual process that they do automatically and reflecting on the whys, etc.
* If some of the information is amenable to giving a talk to other employees, with a Q&A section, that might work, too.
* Another option is to have another employee interview the person leaving about one or more topics, and either type notes as they go, or record it and get a transcription. The interviewing person should be able to understand the topics.
* For tasks the person leaving does, you could have other people do the tasks while the person leaving is available for questions, and one of them documents as it goes. Depending on the task, it might make sense to have the knowledge-holder right there, both answering and observing, rather than only available for questions on-demand.
Side suggestion about accessibility/discoverability/maintainability of all this new documentation: consider keeping the medium simple, and avoiding a proliferation of locations, formats, a dozen bullpoop communication SaaSes, etc. For most software work, for example, inline embedded source code comments and API docs can be an easy way to try to keep a lot of information accessible in context and maintained. Some other information that doesn't fit well in source code, such as ops architecture and procedures, might be Markdown files in that same code repo, or another one. The occasional video file you just can't check into git might be a rare indispensible one, but can still be linked from a Markdown file that's in your repo, but even then, maybe you also have a text transcript in the repo, or someone turns a talk into edited docs in the repo.
Incidentally, much earlier in organizational knowledge sharing, I vaguely recall a study by a consulting firm (sorry, no cite handy, and I'm not 100% sure I remember which big-name firm), in which they found that people were resistant to having their knowledge captured in a system, because that knowledge was an asset of the individual. Your key people leaving might be more altruistic than that, want to help out their colleagues, want to have a good word-of-mouth reputation, have a sense of professionalism about it, have equity in the company, etc. You might like them to do knowledge transfer to a degree that's really above&beyond the call, so consider how you might acknowledge and thank them for that. It might also be a good example for others, and promote more proactive good practices for organizational knowledge.
Edit: Yes, they'll hate it, but this should include a tour of duty Sales. Poor relationships & acrimony between sales & dev are based on a failure of understanding each other's jobs. And sales are the closest to the needs of customers, short of sitting with customers themselves.
1) what is it? (A web project, an automation script, an ansible deployment repo?)
2) what dependencies do I need to run it? (Make, NPM, Java 1.8?)
3) how do I run it? (docker-compose up? make && ./a.out?)
We started with this. Then for the bigger projects/monorepos, we started adding README files in relevant subfolders.
Recently I've been converting these README files in the larger projects into mkdocs subfolders that get hosted in our repository tooling (GitHub/GitLab pages).
Start small. Go slow (if it's institutionally difficult). Build up to more complexity as you get more written material to work with.
I've started creating an "index" project, that links to all the projects that have documentation.
And finally, focus on the pain points first. One of our monorepos was fiendishly difficult to deploy correctly, either locally or in a test / production environment. The very first tutorial I wrote was setting up that environment in a step-by-step, repeatable manner, and it's by far the most oft-used documentation we have. With that out of the way, I can focus more on the esoteric details (and, yes, unfortunately, it's a bit of a thankless, "skunk works" project, but it's worth it)
For something even better than a README, you could document the steps of a technical procedure in a Makefile (or Fabfile) that your colleagues can run. It's important to keep the scripts readable and stupid (as opposed to abstract and powerful like ansible), so that people can read the steps. Some people refer to this as "runnable documentation."
Conceptually this is similar to having a wiki, except for that unless your company has people whose full time job it is to maintain the wiki then it will always be out of date and inaccurate; just deploying some wiki software tends to be pretty useless, and even in the rare cases where they are maintained the medium inherently doesn't preserve the tacit knowledge contained within the decision-making process itself.
Being able to
grep -A3 -i foobox -r /nfs/info | grep -i rpc
is useful. Similarly, you can shove plaintext into a more advanced search engine easily.
I think you can, the main issues are that:
- Conversations aren't forced to be threaded, and there is no way to go back and do anything with conversations that weren't threaded; it's just lost data.
- Because Slack doesn't export data into a standardized format, there isn't a big ecosystem of tools to do stuff with Slack data. And it's not clear that there will be in the future either -- Slack's growth has started slowing substantially and it's only around 13M DAU, which isn't really big enough to build a business on top of.
But I meant more like if you can get 1 / 1,000 email users paying you $10 bucks a month then that's $480,000 per year, whereas 1 / 1,000 Slack users is $1,560 per year.
If you can set up a culture of everyone subscribing to internal mailing lists with searchable archives and wide distribution then I could see it working - but my experience is that the easiest way to get that culture is to switch everyone over to Slack.
Often there are many ways that changes are communicated (for example, an email to the NOC team to advise of systems being decommissioned, an email to the helpdesk to advise of new support procedures, etc). To some people, that email is the documentation. I know that if I want it captured in the knowledge base, that email is my cue to transpose the notification email into documentation that can be referenced later.
My current job is doing sysadmin support for a consultancy, so there are lots of clients and lots of other people doing this work. We have a regular pager rotation for emergencies, so if you get an overnight call to work on something and can't find the information about it, you start to realize how important the docs are. That has been a big motivator in getting people to update docs about the things they know. If you don't want a call overnight, make sure there's nothing that isn't in the wiki!
I use plugins to help point out when content might be out of date, and guide people to archiving out-of-date docs, or to update them. I regularly refer to Stewart Mader's great book Wikipatterns and its list of patterns/anti-patterns to help with wiki adoption and behavior. http://stewartmader.com/wikipatterns/ The book is a great read and covers a lot of your questions, especially skeptics and opponents, and how to address them.
I had a co-worker write about the importance of documentation to folks who are on call, and why it is hard to get it right: https://www.transposit.com/blog/2020.02.26-rewarding-documen...
The two biggest challenges I've seen over and over again are:
1. People don't document changes well. You end up with pages and pages of outdated documentation describing things as they were years ago. This is especially hard on companies that have multiple teams using same underlying platforms/frameworks/libraries. Each team is going to create documentation on how they're using it when they do the work. Once the underlying technology does a version change / incompatible change, all of that documentation becomes obsolete but remains in the knowledge bank polluting the search results. I've become convinced this is an unsolvable problem.
2. Search. I have never seen a documentation system that gets me the information I need easily. It's closely tied to the problems described on the previous issue, but also almost all search systems I've seen are really bad at identifying the authoritative sources of documentation and pointing you to them as the first result.
Also think of your audience. The best documentation I've seen clearly separates documentation intended for maintainers of the code and users of the code.
I usually also try to budget a day or two at the end to look at the documentation and generally clean it up. I can't always get "fresh eyes" on it per se but at least I can make sure it seems to basically flow.
The side effect is your major project also comes with basic documentation for very cheap. Honestly, it may even be "cheaper than free"; I do this because I think it helps make better code, faster. The act of writing the documentation doubles as a self-directed design review, and I couldn't even tell you the number of times I've documented some particular thing only to realize how stupid it is before I even wrote a single line of code [1], and started rearranging things at the cheapest development stage there is. But I concede in advance that proving it's "cheaper than free" is pretty hard.
I don't present this as a full organizational solution, of course, but unlike those full organizational solutions, this is something anyone reading this can pick up and start trying out tomorrow, whereas "redo how our organization conceives of how we store information" is a bit less immediately actionable, shall we say.
[1]: "Wait, I'm requiring what precondition of the callers? Wait, I'm going to return six values? (Better make a new struct/class/object.) I seem to have an awful lot of functions asking for the same 4 parameters (again, new struct/class/object). I'm asking for how many incoming parameters? These are awfully complicated instructions I'm giving about what they can and can't do to the return values. These instructions on the transactionality of this call are stupid complicated." etc.
I argued with my boss and finally got a vm with a MediaWiki instance. I created a simple frontend using Javascript and html to simplify correct addition of common page types.
Obstacles: my boss and certain other people wanted something more businessy. Also they wanted to run the DB on MSSQL, while MediaWiki is supposed to use MySql I think.
At a later place I was tasked with moving/updating documentation from a two page Word document to a Confluence document. It was written by a long time developer so it grew quite a lot.
Obstacles: Confluence :-] Also getting people to admit when their previous docs are wrong (or at least deviates from official vendor docs, and it creates problems.) Also trying to keep it up to date while others are constantly changing things.
Later on I've
- used OneNote,
- got others to use OneNote
- failed to get people to use OneNote,
- updated Confluence plug-ins,
- struggled with people who said they used README-driven development, but were really just their personal notes on what they'd need to remember.
Finally there are some common theme:
- refusing to acknowledge the need for any system beyond mail and Word documents.
- insisting on buying one lf the "commercially supported" but otherwise inferior and close to unusable system
- insisting on using SharePoint (a variation of the point above)
- putting everything into Confluence which means hopeless search + access restrictions so you never know if 1) the document exists but you don't have access, 2) it exists but you cannot find it because it is in the wrong place and search is broken 3) the document doesn't exist.
1.) communicate asynchronously as much as possible. If you have a synchronous conversation like a meeting, make sure there is a written representation of what was discussed. If it doesn't persist, it doesn't exist
2.) Understand that implementing a wiki by itself will not work. There's a gravitational pull to throw a bunch of junk in it (like a file cabinet). Things become out of date and each person will structure things in a different way.
3. Create some loose structure around sharing regular, written updates about what each person/team is working on.
At my company (https://www.friday.app), we've created a tool that is somewhere in-between Slack and a wiki. It's kindof like a work journal. As a distributed team who only has 1 meeting every week, it's a place where all our updates are captured in a single place.
- The code change itself
- Tests that demonstrate that the change works as expected
- Updated documentation relevant to that change (documentation should live in the same repo as the code to support this)
- A link to the ticket/issue that discusses the change
If you use a code review system such as GitHub pull requests or Phabricator you can enforce this kind of commit culturally - in your review point out that the test is missing or the documentation hasn't been updated or there's no link to an issue.
I like building pull requests up from several commits and then using the "Squash and merge" option to merge them into a single commit to master that includes all of the above.
Doing this is great for institutional knowledge, because "git blame" can always lead you to a comprehensive explanation of the change, including a link to the underlying ticket where the change was originally requested and discussed.
I'm more inclined than most of my team to do cleanup commits, but even I sometimes avoid them just for the extra cost of the regular review process.
I think a better approach is to have a culture that encourages making context dependent judgement calls, which is also what I try to do.
If it's something trivial like fixing a typo, I ask that this is made clear in the title, so investigators of an issue know that this CL is unlikely to be relevant.
If it's a minor change in behaviour, I ask for a commit message, and/or a comment in code, with a motivation of why it's needed.
If it's a bigger change in behaviour I want an issue linked to it, to make tracking easier in case there's followups needed or there's some regression due to this.
All this is of course based, not on some platonic ideal of what makes for good documentation, but rather on real experience of tracking down issues and adding features.
I know how annoying it can be to track down the commit of some functionality that looks really odd, only to find an empty message without even a reference to the issue that was being solved. But I also don't have this problem with commits that are clearly labeled "Fixed typo in X", those I can simply ignore.
Encode your knowledge into software, into data structures, into tests and active documentation.
Human organisations have faced these problems for thousands of years. And never solved them well. Maybe we need the new kid on the block to help
Optimizing things (and organizations) tends to make them efficient but brittle. This is another area where that's true.
When you think about it, a lot of corporate cultures reward the opposite -- employees hoarding key knowledge so they can use it to their advantage.
To do this, avoid creating a culture that fosters rivalries. I know it's controversial to say this, as many business people seem to think that brutal rivalries are what leads to over the top effort.
Instead, think about the knowledge as processes, and figure out how to best codify and execute those processes.
If you arrive at a step in the process that appears to be something that can only be done by one person, or by a person who is leaving, that is a clue that someone is withholding information or trying to use it to his/her advantage. Nothing is that complicated, just break it down into simpler steps.
Then, when it comes to onboarding, introduce whichever processes make the most sense for the new hire, and encourage him/her to view them both as an example of excellence but also as something that can be improved. Doing this helps the new hire understand the design perspective behind the processes, which is preferable to following them by rote (which is surprisingly common even among otherwise bright people).
It sounds from the question that you have a bit of drama going on, so you may actually want to sketch out the processes as you think they are and then incentivize the team to make them all precise.
- comments in the source code
- commit messages
- readme
- code review
- pair programming
- variable naming and refactoring
Which is all great, but at the same time narrow. What if I want to capture institutional knowledge when it comes to accounting, HR, PR, management, negotiations, suppliers, local laws, seasonal patterns etc. Perhaps there's a more abstract, generalized advice that could be applied outside of the realm of coding.
comments in the source code
This is an unpopular opinion, but I fervently agree with it.It one of the most powerful ways to keep a codebase comprehendible.
Some folks say, "That's what commit messages are for." Bullshit. When people say that, I suspect they've never worked on anything other than prototypes or toy projects. Good commit messages are a must, but they don't scale well when it comes to long-lived projects. Think of a source file that's had many dozens or hundreds of commits and refactorings. Tracking down the original author's intent can be very difficult - especially when the original commit doesn't reference what's happening on line 78 or whatever. Especially when there are dozens of such oddities in a single file.
Some other folks also say, "Good code is self-describing." Again, bullshit. Maybe if you're writing code in a vacuum. But code gets weird and messy where it interacts with other things that are outside your control. I can read your code and see what it's doing. But your code cannot tell me the "why." The kludges you implement to work around bugs in other libraries/browsers/APIs are NOT comprehensible without some contextual information about the bug you're trying to solve. Ditto for all the weird business logic that creeps into applications. Why aren't we charging sales tax on Topeka on Tuesdays? Tax law? Were we running some special promotion? Did our vendor in Topeka already collect sales tax in some other part of the process? A quick comment can save the next maintainer hours of wondering.
So, my rules are....
1. Stick a comment in there if you are implementing a kludge/workaround based on some external thing. Wrote your own CSV parser because the one in the standard library is broken? OK, tell me that so that I know this was a conscious choice and not a matter of you simply not knowing that the standard library existed.
2. Stick a quick comment in there if you are implementing business logic. Even if your comment is simply "Implement Bob's marketing idea for the job fair" that would at least give me something to go on five years from now when I'm wondering if I can delete that bit of code.
3. No need to document basic stuff. Retrieving some records from the DB? Writing to a file? No problem. Assume the person reading your code is a competent programmer. No need to describe that stuff.
Yep. I've seen codebases that have migrated source control and issue trackers multiple times - sometimes migrating history, sometimes not. The only ancient knowledge that has survived is the code comments.
When I manage engineers, I insist on people having the old-fashion pen and paper notebooks: not scratch paper; not pads; not post-it notes. Simple 5 by 7 grids. During my weekly one-on-ones, I encourage people to make one or two positive changes:
* jot down any odd term they run across so they can google 'strangeNewTerm slides' later and batch through them all * write a quick note on any error taking over twenty minutes * go back and read their notebook here and there
People do use the notebooks, do record the information, do get sick of writing and do start reaching out for other ways to record information. I allow people to use Wikis, markup files, documents, or a mishmash: people are more likely to work on their own idea. I do insist that documentation be in source control and have 'section last updated' dates. Eventually, I encourage someone to maintain a master index of where non-code documentation is found.
The hard part is getting people not to document too much. Every document has a maintenance load, much like every line of code. It is far better to have an up-to-date hint like "TPS reports need cover pages per YoyoDyne contract, 3/2004" than volumes of out-of-date procedures, one of which mentions the YoyoDyne contract on page 37.
One totally different tact: new developers get assigned to the source code control review. That is, they look at the new commits; run the new code, update the project/company specific dictionary with any new terms; give the tests a careful reading and add to them; and write down any question. New developers quickly become familiar with the code base that is most likely to change.
Not sure who you are managing, but for me being told how to take notes would be a huge red flag.
Give your people some autonomy.
In practice, you can revisit even a small point like taking notes as often as the other person finds experimenting with your advice makes her a better engineer.
The answer is by requiring close team effort. Pair programming for example.
I’d one person leaves the organization, there should be “adjacent” employees who understand what they contributed.
The end result is that everybody knows enough to pick up where somebody else left off. We can review each other's pull requests effectively and go to each other for questions.
I'm not sure I like the pair programming or the open office environment, but I haven't tried anything else yet. Sometimes I think pairing slows us down. And we sit right next to a tech support team that's on the phones all day...
What’s dumb is to do it Kent beck style, both people on the same keyboard at the same time. Cargo cult. I bet that’s how y’all doing it, judging by the open office comment.
Pull them off, and assign them to a cushy knowledge transfer process. You'll more safely learn about your true dependencies & get some of the knowledge you want at the same time.
2. Corporate university
3. Culture of anti-knowledge hoarding, pro automation, well-documented procedures and no "we need Joe, only he knows how to do vital task X."
4. Succession planning
Part of the knowledge of a large system is due to having discussions with others.
Something I wished companies do is to ensure that discussions happen in internal mailing lists (rather than in individual email accounts) and have all mailing lists searchable and accessible to anyone in the group. This would simplify understanding how certain decisions were arrived at.
Applied carefully this can really help encourage a culture of documentation that stays up-to-date. You can't land new code if the tests are failing, which means you at least get reminded that documentation is something that you should be thinking about.
I wrote about this technique here: https://simonwillison.net/2018/Jul/28/documentation-unit-tes...
Have people document how they diagnosed problems after fixing it, including queries for searching logs.
Thank people for documenting things.
However, to make the institutional knowledge useful, it must be easy to find. Thus, I think the second most important thing for capturing institutional knowledge is to have a small number of easily searchable places where documentation lives. Markdown files in the source are convenient place for documenting particular projects or code, but more general-purpose knowledge should be in a wiki or any other document store that is centrally searchable and update-able. An example of such general purpose knowledge is "how-to knowledge": How do I request the appropriate privileges to integrate my service with Service X? How do I make and deploy a staging build? How do I set up a new service?
Another sort of general-purpose knowledge that should have a single home is knowledge around context for past decisions that were made for good, but not obvious reasons. My team maintains a document called a Decision Log, where we record the context around and reasons for every decision that required more than roughly 10 minutes of thought. Longer decisions have their own docs, but they are linked from the central Decision Log.
Has to be easy to use, easy to write to in particular, and quickly searchable.
Resist all attempts to impose process or standards to wiki entries. If that fails, create a second, "draft" wiki immediately.
A few people are quite disinclined to write things down. A few others are quite inclined. Most of us are in there middle. It's important to remove barriers and make it easy. Think of it as a product that users have to want to use.
* Graduated levels of mastery: few people need the details for standing up a production database, but all department members need to know that a company process already exists for it.
* Training dependencies: the mapping doesn't have to be perfect, a little goes a long way in giving shape to a training program.
* Training records: log employee training sessions, from self declarations of 'Yes I read this brief' to consultant led seminars.
Basically 80% of the military's comprehensive training program can be implemented with a network drive of docs and a spreadsheet. A couple of places I contracted for was pretty heavily reliant on Microsoft Sharepoint. I'd be surprised if there wasn't a fairly decent open source suite of components that could give you a solid starting point for a training program what would be somewhere in the middle of the spectrum.
Try speaking to people in real life. It's not that hard.
* let people work in small teams/duos
* share knowledge by using a Wiki [1], especially the leaders (the flexible people) should write down as much as possible, but collaborate on the knowledge base (answer questions, add stuff that's missing)
* take meetings as needed (don't overdo this, nobody likes to sit in unnecessary meetings)
* automate as much as possible, the common developer does not need to know exactly how the build pipeline works (but a few people should)
* let people try out new things, this keeps them motivated and improves themselves as well as spreading their own knowledge to co-workers
[1] I found this to be very efficient if you have a team that has the right mindset. If you start out with people that are not used to document stuff, it'll be hard to get your knowledge base going. You can take a look at the product we build Emvi (https://emvi.com/), which aims to solve some of these issues.
A good code review culture also improves knowledge sharing: We sometimes have two paragraphs of explanation in a pull request that changes one line of code. Those pull requests are forming a part of our institutional knowledge base and they are oftentimes referred during future conversations about past decisions.
The team should understand that spending a bit time today to write things down will save much more time in the future when the same thing has to be explained again and again. Also the team should be encouraged to spend this time on writing documents and not punished because of not starting with the next game-changing product feature.
You need to get (particularly, senior) engineers to buy into the mindset of documenting everything and making the documentation the first place to look (not after all else fails). Leads should hold be held accountable for their docs meeting some standard of "this is a useful doc".
If I were in your shoes I'd get senior engineers in a room and be honest with them about the situation. You're going to need them to do work that they might not be naturally inclined to do, or work that might not seem like a "productive" use of time. You might want to get them to agree on what a good doc looks like (the standard), and what things need to be documented. Maybe take a whole day to do this, with snacks and coffee. Good luck!
Powerpoints lunch-n-learns and confluence pages.
Whatever it is it has to be there front and center with the day to day work. Enforcing good commit descriptions, a code review process where a project manager is part of the merge to capture things usually lost in the technical minutia would be my best guess.
For tacit knowledge, the traditional form of transfer is simply interaction in the course of work. having a searchable archive of conversations is valuable. In most organisations, people are only able to search their own emails but not others. Chat is helpful for finding institutional knowledge around simple problems but not optimal for deeper and more thoughtful discussions that tackle larger issues. This is why I’m currently working on TribePulse, an internal discussion platform, designed to surface and capture institutional knowledge.
When you talk to the outgoing employees, ask yourself if the processes they are describing are even processes that are replicable or controllable by the organization.
So, for example, are people putting things on their own credit card and getting reimbursed? Is this potentially a problem? Do you need to arrange a company credit card so the organization has real control here?
Then you need to document things. But don't just assume that the architecture is even there for the institution to be in control. You may need to create that piece as people leave.
Another is calling an impromptu huddle when I'm about to work on something that nobody else feels prepared to handle on their own. When some crazy bug crops up that I'm about to troubleshoot, I'll often ask a few other team members to shoulder surf while I talk through the approach I'm using to run the bug down. It's a great time to ask the group what they think we should do to test their knowledge.
Let's be honest here. There's nothing you can do to prepare for the loss of these people. You are coming at the problem too late. It's a cultural problem, not a procedural problem.
To fix the problem going forward, you need to establish new cultural norms. Force new employees to document what they find as they learn the codebase and the "processbase". Establish a new norm that a thing must be documented appropriately at each stage before it can progress to the next. There has to be real pain incurred (schedules missed) before this will really start to work. Management needs to have the will.
https://slab.com/blog/knowledge-hoarding/
It's not a direct pitch to use Slab. In it we talk about the three reasons we discovered most folks hoard knowledge:
1. Leverage: If an employee hoards their knowledge, they may feel like they are irreplaceable. 2. Fear: Putting yourself out there can be intimidating. What if colleagues or supervisors respond with negative feedback? 3. Competition: If your workplace rewards personal triumphs over shared victories, employees are less likely to want to share their "secrets."
Also, no matter what documentation tool you use, it's worth reading this first: https://slab.com/blog/documentation-tools/
Many teams initially gravitate toward more generic document editors (Google Docs) as their first team wiki, for logical reasons:
- These editors are familiar to most people, meaning they can be easier to adopt across an organization - Most companies already use (and pay for) at least one of these tools - Teams realize the need for documentation, but aren't thinking of how their documentation tool will scale alongside their business
But there are some issues with these document editors that teams discover as they grow. This article dives deep into those shortcomings. Here are both article links again, and good luck!
1. https://slab.com/blog/knowledge-hoarding/ 2. https://slab.com/blog/documentation-tools/
Knowledge is 'institutionalized' via experience first, documentation/formalization second, schools based on that documentation third, mass media fourth, gossip and other forms of informal communication fifth.
Stick with boring tools, boring tasks, then they can be replaced with boring people who won't quit to work on the next cool thing as long as the paycheque is right.
We have videos, slides, spreadsheets, docs - we always try to use the best format for the job.
It's not perfect but you're right in that it has a huge impact on the efficiency of certain processes and therefore, scalability.
Disclaimer, I made this app.
https://zwischenzugs.com/2017/04/04/things-i-learned-managin...
Specifically here, the importance of:
- allocating budget to the maintenance of knowledge
- rotating the responsibility for maintenance around the group
- co-locating the knowledge store with the day-to-day tooling, even if that doesn't conform to document management ideals
E.g. Create tutorials on setting up a development environment, installing dependencies, compiling modules, running tests, creating new components. Write descriptions at a high level of the system, make diagrams of complex message exchanges. Write down best practices, or paste boiler plate code for doing specific useful things.
2. Always have an agenda. Always have someone taking notes. Notes must be reference-able (public slack channels count, wiki is better, email doesn't).
3. The first item on all new hire's onboarding: every time you learn something that's not in the documentation, or incorrect, update it. You will be explaining this to the next new hire.
4. Hire a journalism major intern to conduct interviews and cultivate archives.
I am in the process of implementing Wiki.js for my team, to a lot of excitement.
Institutional knowledge comes not just from managers, executives, and team leads, but also from those “in the trenches.” The finer details of operation can be lost the higher up on the org chart you go, and that’s where a well-organized and liberally maintained wiki (or other team knowledge base software) becomes invaluable.
So I built a custom internal search engine that indexed documents from all of those systems and made them searchable in one place. It worked pretty well!
Also be realistic about how the documentation will be used. I found this paper and its references useful:
They capture why a decision was made and the context/options at the time. They also provide an immutable linear log of decisions which is nice for on boarding.
https://github.com/joelparkerhenderson/architecture_decision...
The culling of deprecated stuff is too hard. The incentives are all wrong. And it's drudge work.
My proposal:
We need to time box and auto expire everything. Like TTL leases. Renew leases on active work. Everything else enters the grooming process.
Have stages, like Trash Bin vs hard delete, to minimize impact.
Unfortunately, people who already know how to do something tend to skip over crucial bits in their explanations and documentation: "break the eggs before putting them in the pan".
Shameless plug: I'm working on a tool to help teams define/share the internal jargon that always seems to develop whenever humans work together: https://jargonaut.net
If that isn't in place. Any such endeavours will fail as other people in the business just won't bother.
Provide lunch. Have the talks be about something very specific in your infra, a company value, a goal whatever.
But just short of compulsory, make people want to give and attend...
I'm in a regulated industry, so this is probably overkill for a web shop.
Essentially, we monitor network communications and rank participants in the network by expertise, skills, workstyle, etc. Then we rank content they discuss / share based on expertise (for search). The system will also rank the participants (employees), and monitor the influence.