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

171–180 of 220 posts

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

#171

Post by emiliobumachar »

Have a wiki that anyone in the company can write to without knowledge nor approval from anyone else.

Has to be easy to use, easy to write to in particular, and quickly searchable.

Resist all attempts to impose process or standards to wiki entries. If that fails, create a second, "draft" wiki immediately.

A few people are quite disinclined to write things down. A few others are quite inclined. Most of us are in there middle. It's important to remove barriers and make it easy. Think of it as a product that users have to want to use.

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

#172

Post by Izkata »

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…

> with clickable links direct to Jira or whatever - e.g. "// This does - see the discussion in http://bug tracker/12345678" )

That does tend to be a great help if people follow it. One problem though: We're on our 3rd tracker since I started at my job. Lots of knowledge in those old cases disappeared because of it.

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

#173

Post by closeparen »

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.

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

#174

Post by jupp0r »

CharlesMerriam2 wrote: post #169

The best is the enemy of good here. When I manage engineers, I insist on people having the old-fashion pen and paper notebooks: not scratch paper; not pads; not post-it notes. Simple 5 by 7 grids. During my weekly one-on-ones, I encourage people to make one or two positive changes: * jot down any odd term they run across so they can google 'strangeNewTerm slides' later and batch through them all * write a quick note…

Somewhat off topic:

Not sure who you are managing, but for me being told how to take notes would be a huge red flag.

Give your people some autonomy.

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

#175

Post by AmericanChopper »

MaxBarraclough wrote: post #121
AmericanChopper wrote: post #103

Earlier quoted context omitted.

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.

> major shortcoming is that it’s not accessible enough for non-technical teams to maintain At the risk of just mirroring my comment above: Low-level nuts-and-bolts documentation can't be accessible to non-technical people, by nature. Documentation of high-level designs are another matter. Why not use a wiki for the documentation of high-level decision-decisions? A wiki can be accessible to non-technical staff, and it…

> Why not use a wiki for the documentation of high-level decision-decisions?

Because if you create different solutions to meet the publishing preferences of different groups inside the organisation, then I don’t think you’re meeting the goal of institutionalizing the knowledge. If a consumer wants to find some documentation, you don’t what their first step to be trying to find the system it’s stored in. Especially in very large organisations, where you could easily end up operating quite a few different publishing platforms.

SharePoint is the closest things I’ve seen to a one-size-fits-all solution. But SharePoint is rather terrible to use.

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

#176

Post by schmichael »

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.

Fair. I find writing a useful exercise even if no one ever reads it (although processes should enforce someone reads it; like a PR).

Calling a meeting anyway is great! You have a document to reference to guide the meeting, answer questions, and scribe discussions/decisions! If your worst case scenario is that your technical document becomes a glorified meeting agenda, that's not so bad.

Also remember that documents live ~forever, so even if you get no immediate response: write for your replacement 5 years from now who has to figure out wtf you were thinking. :)

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

#177

Post by Izkata »

heavenlyblue wrote: post #148
fsloth wrote: post #133

Earlier quoted context omitted.

This was not about inline documentation in source, but about separate readmes. If a hand typed ascii graphic does not suffice for code comment embedded docs, then it would be better to include separate docs altogether.

There is a reason why everyone uses LaTeX (or similar) when it comes to professional content delivery - it actually saves you time not fighting the editor.

> it actually saves you time not fighting the editor.

And from merge conflicts.

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

#178

Post by alexashka »

How do you make people replaceable? By sticking to org structure with roles that most other companies in your sector use, so that they can be replaced by other people who have worked in other companies.

Knowledge is 'institutionalized' via experience first, documentation/formalization second, schools based on that documentation third, mass media fourth, gossip and other forms of informal communication fifth.

Stick with boring tools, boring tasks, then they can be replaced with boring people who won't quit to work on the next cool thing as long as the paycheque is right.

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

#180

Post by allannienhuis »

Izkata wrote: post #172
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…

> with clickable links direct to Jira or whatever - e.g. "// This does - see the discussion in http://bug tracker/12345678" ) That does tend to be a great help if people follow it. One problem though: We're on our 3rd tracker since I started at my job. Lots of knowledge in those old cases disappeared because of it.

Keeping read-only archives of the retired bug tracker seems like the right thing to do - even if that had to be done with an external archiving tool (top hit on google: https://www.petekeen.net/archiving-websites-with-wget)
Post reply on HN