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

191–200 of 220 posts

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

#191

Post by dlivingston »

Here’s a bit of a different answer: implement a company-wide wiki (if your company is medium-to-small sized).

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.

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

#192

Post by phkahler »

I would guess a lot of what you want to preserve is wisdom. You keep that by retaining the older folks that have it, and have them work alongside the younger people that dont. I've learned so much from other people's war stories. More than from any lessons learned database. Documentation is nice too, but writing it and reading it take time and it doesnt always cover the things that didnt work.

Optimizing things (and organizations) tends to make them efficient but brittle. This is another area where that's true.

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

#193

Post by tatar »

Drdrdrq wrote: post #154
Techies4Trump wrote: post #91

Earlier quoted context omitted.

Solo people working on projects aren't too bad so long as they communicate the work they're doing and document it well. 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. The…

> Solo people working on projects aren't too bad so long as they communicate the work they're doing and document it well. 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…

I've found your comment compelling. I'm assuming you have some unit economics implied here, I'm very curious to learn from your experience.

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?"

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

#194

Post by fsloth »

heavenlyblue wrote: post #183
fsloth wrote: post #164

Earlier quoted context omitted.

There's no reason why internal readmes should be of 'professional quality'. It's nice, but a low barrier of entry to explain something non-trivial is more important than nice layout, IMO. "Everyone" is not using LaTeX.

Yeah. Except WYSIWYGs take way more time to do anything non-trivial. 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.

By Wysiwyg I was referring to Word or OpenOffice or Google Docs or whatever the generally used word processing tool in the org is.

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

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

#195

Post by fsloth »

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…

I think it's most important that every line changed in production code can be backtracked to a ticket in the "feature management database" whether it's Jira or whatever. This simple rule helps immensely in keeping codebases in good shape.

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.

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

#196

Post by oneplane »

fsloth wrote: post #195
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…

I think it's most important that every line changed in production code can be backtracked to a ticket in the "feature management database" whether it's Jira or whatever. This simple rule helps immensely in keeping codebases in good shape. 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) bu…

We split it out: non-ticketed changes are recorded by forcing commits with specific commit formatting that puts out a changelog at intervals. That gets you a log of changes that can be either tracked back to a ticket or are self-describing.

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

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

#197

Post by asdff »

closeparen wrote: post #173
schmichael wrote: post #33

Write write write and keep writing. Then expect to do 10x as much reading. It's exhausting and definitely relies heavily on employees' writing and reading comprehension skills. 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 descrip…

It’s demoralizing to write write write when you know no one is going to read, and if you link them something more than 100 words long they’ll ask for a meeting instead.

But occasionally you find yourself years later giving your own thoughts a read read read, and it's helpful that you've taken the time to write write write. Future you will thank you. I'm pretty happy with past me for obsessively documenting some things.

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

#198

Post by asdff »

mandelbrotwurst wrote: post #70
dehrmann wrote: post #56

Earlier quoted context omitted.

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

Your position is reasonable. The value of spending time on documentation in a vaguely specified and frantically written web app is not the same as, e.g. writing documentation for the frameworks that drive that same application.

Even with the most frantic half effort of a project, its helpful to give the context of why you are doing it, why you approached the project this way, and why you ended up not going with another approach. Maybe you did try what should have been the best approach at first, and it didn't work right, so you had to do something not as good but good enough. Then in the future someone decides to try to redo what you've done using the best approach, and they hit a wall because you never wrote down that you tried that and it didn't work for x reason. Writing up what you do helps keep your own thought process organized, so it's beneficial for you even if you never read what you wrote.

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

#199

Post by asdff »

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)

I feel like the stars would have to align for that kind of crime to even be found. I think it's a guarantee that it's already happening in a lot of companies. So many companies have the most sloppy book work, and regulatory bodies are stretched too thin to catch everything.

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.

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

#200

Post by nelsonic »

pmontra wrote: post #168
nelsonic wrote: post #123

Earlier quoted context omitted.

We use the Markdown file method extensively at our company. see: https://github.com/dwyl?&q=learn But just asking/reminding people to capture learning/knowledge in Markdown is not enough to ensure that it actually happens. If the organisation does not have a learning and sharing culture at all levels having markdown files falls apart quite fast! see: https://en.wikipedia.org/wiki/Learning_organization People first ne…

Doing homeworks together was ok, sharing answers to tests was not. Anyway, the goal there was to score individual students, the goal here is to build something together. Of course some people want to outshine coworkers or try to become not replaceable, so they won't share anything unless forced. This is probably your point. A way to measure people's contributions could be counting how many times those lines in the wi…

Yeah, agreed. But sharing the answers is exactly what is needed in companies/organisations. I've worked in companies where people hoard data and solutions to problems because it gives them power/influence/job-security.

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

Post reply on HN