Ask HN: Good ways to capture institutional knowledge? • Hacker News Board

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

#151

Post by MaxBarraclough » Sun, Mar 01, 2020, 3:05 PM UTC

dharmab wrote: post #149

MaxBarraclough wrote: post #120

Earlier quoted context omitted.

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

This isn't for comments directly on the source code, it's for higher level stuff like "These are the three services that interact to provide such-and-such functionality. Here's their basic architecture, their dependencies and some basic troubleshooting knowledge/tips."

Right, but isn't that what I said?

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

#152

Post by mlthoughts2018 » Sun, Mar 01, 2020, 3:17 PM UTC

herval wrote: post #74

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…

How do/could you quantify the benefits of this culture? I frequently manage groups of “move fast & break things” folks, and RFCs/design docs/etc are a very hard sell (in particular when teams are fully local)

Over the years my perspective on this shifted a lot. I now feel it’s not worth it to convince people of the need for RFC / design spec process to ensure alignment prior to implementation.

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.

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

#153

Post by Alex3917 » Sun, Mar 01, 2020, 3:29 PM UTC

simonw wrote: post #85

Alex3917 wrote: post #29

Earlier quoted context omitted.

> Can you export slack logs as plain text, or something easy to process like JSON? 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…

13m DAUs at $6.67 per month is $86,710,000/month, or $1,040,520,000/year - seems like a pretty big business to me!

Yeah if you can get 13M people paying you then obviously you're doing amazing, but even Slack only has 6M paid seats.

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.

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

#154

Post by Drdrdrq » Sun, Mar 01, 2020, 3:39 PM UTC

Techies4Trump wrote: post #91

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

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

#155

Post by crazygringo » Sun, Mar 01, 2020, 4:00 PM UTC

I wish there was one.

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.

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

#156

Post by schmichael » Sun, Mar 01, 2020, 4:06 PM UTC

herval wrote: post #74

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…

How do/could you quantify the benefits of this culture? I frequently manage groups of “move fast & break things” folks, and RFCs/design docs/etc are a very hard sell (in particular when teams are fully local)

Quantifying human processes is not one of my strengths, however these are some situations a culture of writing helps avoid:

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

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

#157

Post by bearer_token » Sun, Mar 01, 2020, 4:09 PM UTC

1. Incorporate documentation updates into your definition of done - at the task, sprint, and project level.

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.

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

#158

Post by matwood » Sun, Mar 01, 2020, 4:29 PM UTC

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?

At worst, the code is there. This is much better than a person leaving who did some stuff manually.

Obviously additional documentation would be great, but code itself is a minimal type of documentation.

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

#159

Post by matwood » Sun, Mar 01, 2020, 4:37 PM UTC

herval wrote: post #74

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…

How do/could you quantify the benefits of this culture? I frequently manage groups of “move fast & break things” folks, and RFCs/design docs/etc are a very hard sell (in particular when teams are fully local)

Typically the move fast and break things culture also means lots of smaller changes. Scale back the documentation to fit those smaller changes so it does not seem so daunting (RFCs may be overkill).

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.

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

#160

Post by duckmysick » Sun, Mar 01, 2020, 4:38 PM UTC

I noticed a lot of suggestions in this thread assume you want to capture the institutional knowledge related to coding and software:

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