Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Ask HN: Good ways to capture institutional knowledge?

news.ycombinator.com

Post reply on HN
Print view View original

101–110 of 220 posts

Re: Ask HN: Good ways to capture institutional knowledge?

#101

Post by larsrc »

dehrmann wrote: post #56
raz32dust wrote: post #52

1. Working in pairs or teams. Avoid solo people working on projects. 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…

> Common, easily searchable place to put all documentation at. Good search capability is critical. Wiki is ok. 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…

The problem with "Read the source, Luke" is that even if the code is well written (and that's a big if), reading the code only tells you _what_ it does, not why, not why it doesn't do it differently, nor what it may or may not do in the future. It's the difference between programming and software engineering.

Re: Ask HN: Good ways to capture institutional knowledge?

#102

Post by eigilsagafos »

This is a great question and the same pain the led us to start ShiftX. It’s a process based knowledge sharing tool where we have focused heavily on simplicity so that both creating and consuming content is as frictionless as possible. We are just starting to grow the company but are getting great feedback so far from our customers in the Nordics. Let me know if you would like to learn more! https://shiftx.com

Re: Ask HN: Good ways to capture institutional knowledge?

#103

Post by AmericanChopper »

m0zg wrote: post #89
mattlondon wrote: post #86

Store readme markdown files in the sourcerepo along with the code itself. Make sure during review that changes to code are reflected in the markdown. 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 a…

This is what I do. And if the Markdown file is not near the code in question, it's a 100% guarantee you've wasted time writing it because nobody is going to read it. 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.

I’m also a big markdown-in-source advocate. However it’s major shortcoming is that it’s not accessible enough for non-technical teams to maintain.

Re: Ask HN: Good ways to capture institutional knowledge?

#104

Post by onei »

orbital-decay wrote: post #99
Too wrote: post #68

Automate everything that can be automated. Avoid setting up things using GUIs. 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…

Imagine that a guy who automated a certain part of the process just left, and you need to make some changes. Who's holding the knowledge about how X is automated and the thought process behind it?

Ideally, the automation is available and can be read through to divine the steps it is taking to perform the task. As for the thought process, pray that the author left behind hints whether that be in the form of comments in code, descriptive commit messages, etc. Otherwise it gets a bit more tricky.

Re: Ask HN: Good ways to capture institutional knowledge?

#105

Post by alexis2b »

umvi wrote: post #43
jrockway wrote: post #34

Earlier quoted context omitted.

I worked in the finance industry and took the mandatory 2 week vacation and dealt with my coworkers taking the mandatory 2 week vacation. 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…

Has that ever happened? Seems like the stars would have to align for that kind of white collar crime to happen (financial employee who is also a highly experienced programmer who is also highly unethical)

A famous example is the (in)famous trader Jérôme Kerviel who was deemed responsible for a 4.9 billions euro loss at Société Générale.

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!

Re: Ask HN: Good ways to capture institutional knowledge?

#106

Post by Yizahi »

There is only one way - 1) higher management must acknowledge that this is needed, 2) higher management must approve time allocation for these activities (as opposed to stuffing all new iterations 100% with new feature development). Then they push it lower and lower, down to the engineers. No way it will happen in reverse, when engineers decide they want this it usually end with a several disconnected resources, often using different tools and each maintained by 1-3 persons effectively for themselves, because nobody reads what they wrote. Also everyone need to accept that this activity does not have "end", and that it may need multiple reworks along the way. Basically this must be a thing that everyone just does, all the time, however they can.

Re: Ask HN: Good ways to capture institutional knowledge?

#107

Post by onion2k »

Too wrote: post #68

Automate everything that can be automated. Avoid setting up things using GUIs. 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…

That's good technical advice but I don't think it works as far as knowledge capture goes. There are two problems.

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.

Re: Ask HN: Good ways to capture institutional knowledge?

#109

Post by onion2k »

onei wrote: post #104
orbital-decay wrote: post #99

Earlier quoted context omitted.

Imagine that a guy who automated a certain part of the process just left, and you need to make some changes. Who's holding the knowledge about how X is automated and the thought process behind it?

Ideally, the automation is available and can be read through to divine the steps it is taking to perform the task. As for the thought process, pray that the author left behind hints whether that be in the form of comments in code, descriptive commit messages, etc. Otherwise it gets a bit more tricky.

Comments and commit messages are documentation and knowledge capture, but done in a way that's really hard to read through and requires technical knowledge and repo permissions to even access. If your team includes people who aren't developers and you need to review a process it's very useful to have that knowledge in a more readable format.

Re: Ask HN: Good ways to capture institutional knowledge?

#110

Post by woutr_be »

aganame wrote: post #97
woutr_be wrote: post #46

Earlier quoted context omitted.

I work as a software engineer in finance and have to take two weeks of mandatory vacation, but this doesn't deter our team from not writing proper documentation, or writing down domain specific knowledge. 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…

What is mandatory vacatio n?

Two weeks paid time-off, mandatory once a year.
Post reply on HN