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

91–100 of 220 posts

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

#91

Post by Techies4Trump »

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…

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.

They also don't write good documentation.

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

#92

Post by simonw »

Use documentation unit tests - tests that introspect code and then scan the documentation to make sure that specific things are at least mentioned in the documentation.

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

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

#93

Post by juanuys »

hayksaakian wrote: post #39

We record screencast videos demonstrating how to do a process. New people can watch those videos to learn how to do it. 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.

I second videos. In fact, I'm trying to think of a way to make animations showing the interaction between microservices without hiring and animator. I'm leaning towards mashing our integration tests with something like Three.js.

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

#95

Post by ascar »

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…

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

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

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

#96

Post by eitland »

At my first job we were in a similar position I think with lots of churn (volunteers, young people).

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.

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

#97

Post by aganame »

woutr_be wrote: post #46
hlieberman wrote: post #9

Mandatory vacation. This is something that the finance industry has used for a long time to guard against fraud -- it's hard to cover up something if someone else has to do your job for two weeks straight at some point -- but it also serves as a mechanism for requiring you to cross-train people. Two weeks of paid vacation where the company isn't allowed to email them or call them for help: I guarantee that documentat…

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?

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

#98

Post by hermitcrab »

Some years ago (before wikis and the www) I worked on a software product for recording Design Rationale - the decision making process that went into designing long lived artfects, such as nuclear reactors and process plants. The idea being that engineers could find out WHY something had been done the way it had decades after the original engineers had retired or been run over by buses. The product failed, despite some intial interest from big companies.

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.

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

#99

Post by orbital-decay »

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?

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

#100

Post by Geeflow »

simonw wrote: post #79

I started an internal blog - using Confluence, because it was already a tool used by the company so I didn't have to convince anyone to install anything new. 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 s…

I also think internal blogs are a great tool. But I also share your experience of how few people are actually using them. At my current company, it is the same thing: I wrote the majority of posts and a handful of people contributed a handful of other posts.

I guess the 1% rule [1] applies to internal systems as well...

[1]: https://en.wikipedia.org/wiki/1%25_rule_(Internet_culture)

Post reply on HN