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

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

#81

Post by simonw » Sun, Mar 01, 2020, 7:29 AM UTC

Every commit should combine:

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

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

#82

Post by kortilla » Sun, Mar 01, 2020, 7:32 AM UTC

luckydata wrote: post #53

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…

It just means people leaving are not that critical. If they were, you would have that documentation or you would be SOL pretty often.

No, you can still be critical and not have it hurt the company with just a two week absence. Say a product like Uber ceases new development because of a critical developer leaving who knows how to fix the home grown CI. The company isn’t going to go under in two weeks but it doesn’t mean the dev isn’t critical.

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

#83

Post by chasedehan » Sun, Mar 01, 2020, 7:33 AM UTC

simonw wrote: post #80

A trick I've used effectively is to have a "doc of docs" - a document that tells you where all the other documents for a project or team live. 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, wh…

Notion is wonderful for this. It’s like a wiki with the ease of use of google docs.

My company has basically everything on Notion and any time someone asks a question more than once, it gets added

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

#84

Post by simonw » Sun, Mar 01, 2020, 7:34 AM UTC

Alex3917 wrote: post #8

The easiest way is just to make sure product/business discussions happen over email rather than Slack. This way those discussions can be searchable and discoverable by anyone within the company at any point in the future. We make software for this (FWD:Everyone), but there are dozens of other similar solutions as well. That's the great thing about email, because the standards are open you'll be able to extract more v…

I've encouraged teams to switch from email to Slack precisely because it takes non-searchable content and makes it searchable. The amount of institutional knowledge that ends up in personal inboxes of a tiny subset of the team (who then eventually leave the company, causing their emails to be lost entirely) has always terrified me.

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.

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

#85

Post by simonw » Sun, Mar 01, 2020, 7:36 AM UTC

Alex3917 wrote: post #29

remexre wrote: post #17

Earlier quoted context omitted.

Can you export slack logs as plain text, or something easy to process like JSON? (Haven't used it in forever, so I don't know). 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.

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

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

#86

Post by mattlondon » Sun, Mar 01, 2020, 7:36 AM UTC

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

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

#87

Post by eitland » Sun, Mar 01, 2020, 7:38 AM UTC

richardw wrote: post #35

People who have been in the job for a while aren’t always the best people to explain something. 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 yea…

I've experienced that as well (both as a junior and as an experienced engineer):

- Follow these steps.

- If anything is unclear or doesn't work, update it.

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

#88

Post by simonw » Sun, Mar 01, 2020, 7:41 AM UTC

I ended up having to accept that documentation would always end up spread across a dozen different systems: Sphinx/RST + GitHub Markdown + Confluence wiki + Google Docs + Continu + email mailing lists + the customer support website + I found one team using Google Sites + ...

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!

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

#89

Post by m0zg » Sun, Mar 01, 2020, 7:41 AM UTC

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.

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

#90

Post by mitko » Sun, Mar 01, 2020, 7:42 AM UTC

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…

Re: easy search. Slapdash can handle search in all your work wikis/docs at once and is very fast. It can search github/gitlab too. I am part of the team there.