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

121–130 of 220 posts

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

#121

Post by MaxBarraclough »

AmericanChopper wrote: post #103
m0zg wrote: post #89

Earlier quoted context omitted.

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.

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's trivial to link to a wiki page from a comment in source.

It also keeps the source tighter. It negatively impacts readability if the source is full of non-vital comments.

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

#122

Post by MaxBarraclough »

fsloth wrote: post #119
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.

I don't know what the infatuation with markdown is beyond web publishing. Wysiwyg documents have been a solved problem for decades. Use what works on your platform. Markdown is fine until you realize you would like to have figures, images and tables. I don't want to spend my time over trite details of a text based markup when I could spend it actually productively. At that point it's way over easier to use a text pro…

Wysiwyg document tools aren't applicable to comments in source.

You can't have images in source, but if you really need it you could add an ascii-art-style table. There are tools to generate these, such as https://ozh.github.io/ascii-tables/

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

#123

Post by nelsonic »

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…

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 need to unlearn what they were taught in formal education. In school we are told not to share our homework with others and the mindset of individualism persists in most workplaces. We need a way to measure and reward people for their contribution to the collective knowledge.

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

#124

Post by jskrablin »

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…

While reading 'teh codez' can work for a (simple) app it will get you nowhere regarding the whole service architecture/infrastructure.

There can and will be several services/apps working together, external services required for some stuff, different set of configurations for different environments, CI/CD, software packaging, etc...

How we deal with it where I work - service developers/owners are responsible for providing docs for their services. Ops provide infra/CI/deployment/high level 'how all this works together' docs. Everything that can be code, should be code - with it's documentation. Of course there's issue tracker, wiki, commit messages all tied together using issue tracker IDs, etc.

And it still takes time for new people to get their heads around the 'how everything is working together'. Amount of docs we're writing is significant. Some of the docs is auto generated. Time for docs keeping is accounted for at estimating the time required for developing new features. Being a member of a remote team I can't imagine how we could be able to work otherwise.

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

#125

Post by nmstoker »

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.

Yes, screencasts are good, and IMHO people who struggle with instructions seem much better at re-watching the difficult part until they are able to do it than they are keen to re-read a section until they get it right.

However it is often essential to have an alternative form (eg transcription or at least summary of steps) simply because of discoverability - even with brief screencasts it can be awkward finding the content otherwise.

I see a lot of responses here automatically assuming that capturing institutional knowledge is about code, but there's so much more of business processes than code that needs to be captured, even in a tech rich environment.

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

#127

Post by bogle »

onion2k wrote: post #107
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…

That's good technical advice but I don't think it works as far as knowledge capture goes. There are two problems. Firstly, it fails to solve the problem of actually capturing knowledge. In fact, if anything, you're suggesting that knowledge of the systems and processes shouldn't be necessary in order for the business to function and that building a black box that "just works" is good enough. The problem with that is…

I've just had to script an earlier manual process and the last couple of steps couldn't be handled in code. The final log message, written to the console, says, "TODO: Now do this thing ...". So everything is under source control and there's a golden source of truth.

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

#128

Post by prepend »

AmericanChopper wrote: post #103
m0zg wrote: post #89

Earlier quoted context omitted.

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.

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.

I like processing the markdown through Jekyll to create a web site that is used by both tech and non-tech. So the site is auto generated from the last change by an engineer.

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

#129

Post by marvinblum »

Most companies start out with people that are flexible and capable to do a lot of different things. As you grow, it becomes more and more important to have specialists that focus on only a small fraction of the overall work you have to do as a company. Here is what I would do:

* let people work in small teams/duos

* share knowledge by using a Wiki [1], especially the leaders (the flexible people) should write down as much as possible, but collaborate on the knowledge base (answer questions, add stuff that's missing)

* take meetings as needed (don't overdo this, nobody likes to sit in unnecessary meetings)

* automate as much as possible, the common developer does not need to know exactly how the build pipeline works (but a few people should)

* let people try out new things, this keeps them motivated and improves themselves as well as spreading their own knowledge to co-workers

[1] I found this to be very efficient if you have a team that has the right mindset. If you start out with people that are not used to document stuff, it'll be hard to get your knowledge base going. You can take a look at the product we build Emvi (https://emvi.com/), which aims to solve some of these issues.

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

#130

Post by prepend »

onion2k wrote: post #109
onei wrote: post #104

Earlier quoted context omitted.

Ideally, the automation is available and can be read through to divine the steps it is taking to perform the task. As for the thought process, pray that the author left behind hints whether that be in the form of comments in code, descriptive commit messages, etc. Otherwise it gets a bit more tricky.

Comments and commit messages are documentation and knowledge capture, but done in a way that's really hard to read through and requires technical knowledge and repo permissions to even access. If your team includes people who aren't developers and you need to review a process it's very useful to have that knowledge in a more readable format.

I don’t like having extra steps to convert things to more readable formats because it’s expensive and boring and tends to get out of sync very quickly.

If non-tech people on a team need to understand, in detail, a technical process, I think it’s easier to teach them to read through a script than to pay a tech writer to document the script, all the time.

I’ve run into this problem with non-technical project managers who want to understand in detail. If this level of understanding is necessary then it’s possible to scan a source file to read comments.

Or generate documentation from source and dump it on a web server somewhere.

Although lately even non-technical people are able to read and edit markdown files on GitHub.

Post reply on HN