3 ms·

Maybe I’m a pessimist but I don’t really think lessons are learned by companies, lessons are learned by individuals. Postmortems are important to drive home wh

Maybe I’m a pessimist but I don’t really think lessons are learned by companies, lessons are learned by individuals. Postmortems are important to drive home what went wrong, but newcomers won’t read them all. That’s why you need people with experience and people with tenure. What companies sometimes do: They encode lessons into rules, which tend to survive turnover. But that comes with its own set of problems, where you end up having a lot of rules who’s reason is forgotten.

ltbarcly3 7y ago
This has been my experience. I've never worked at a place where the wiki was up to date, or where institutional knowledge was managed in a way that wasn't "ask this person about this, ask that person about that". I think attempts to document things "so we don't forget them" are basically a waste of time for an organization. Keeping notes for yourself can be handy, though.
- lowercased 7y ago
  I mostly agree with the 'waste of time' except... I did work one place where it was expected that you'd update docs/wikis/etc, and that was part of the deliverable. It wasn't perfect, and there was always some stuff that was out of date, but when you found something out of date, you were expected to confirm it and update the doc as 'out of date' - ideally link to the updated page if it was possible. This was not a perfect system - nothing is - but the culture of the group just baked this behavior in to the timeline for 'done'. When the majority of people had that expectation, it seemed to work decently. In 25 years of professional work, that's the only place I can remember seeing it done that disciplined. And... they were only around 100 folks total - not sure it could necessarily scale as they grew.
- henrik_w 7y ago
  I agree with keeping notes for yourself. I think the key benefit is from writing the notes more than the resulting document. The act of writing it down helps you learn/remember the lessons I think. I have been keeping records of the trickiest bugs I have come across for over 15 years [1]. I believe this has helped me internalize the lessons I wanted to learn from them, so I (mostly) won't repeat them. Also, when you leave the company you keep your own notes. [1] https://henrikwarne.com/2016/06/16/18-lessons-from-13-years-of-tricky-bugs/ https://henrikwarne.com/2016/06/16/18-lessons-from-13-years-...
  - happywolf 7y ago
    Nice sharing. Like the tip on 'Own Tools' that has been applied in numerous situations. Sometimes a quick-and-dirty script(usually bash or python) will accelerate things considerably.
- toast0 7y ago
  Adding on, when I've worked where people ask for the wikis to be updated, I've found that nobody reads the documents I have written. Honestly, keeping documentation up to date, and writing accessible documentation is a different job than making the system. If it's important, you need a technical writer on staff to do it, and a commitment that developers need to work with the writer to get things accurate and as complete as possible. It's the same as testing; you can try to make developers do it, but some developers aren't capable of good testing and some aren't capable of good writing, and in both cases, having an independent person doing the work will result in more coverage, since the other person may not share the same "implicit" ideas that the one developer might not document or test.
kqr 7y ago
This is realism, not pessimism. The reason employee retention is so important for software companies (or at least should be!) is that the loss of knowledge associated with replacing one employee is much greater than at first glance. (Well, that and the fact that some things have really long feedback cycles, and you have to stick around for a few years to truly see the consequences of your decisions.)
HalfYawn 7y ago
Behind every sign there's a story :)

ltbarcly3 7y ago

This has been my experience. I've never worked at a place where the wiki was up to date, or where institutional knowledge was managed in a way that wasn't "ask this person about this, ask that person about that". I think attempts to document things "so we don't forget them" are basically a waste of time for an organization. Keeping notes for yourself can be handy, though.

lowercased 7y ago
I mostly agree with the 'waste of time' except... I did work one place where it was expected that you'd update docs/wikis/etc, and that was part of the deliverable. It wasn't perfect, and there was always some stuff that was out of date, but when you found something out of date, you were expected to confirm it and update the doc as 'out of date' - ideally link to the updated page if it was possible. This was not a perfect system - nothing is - but the culture of the group just baked this behavior in to the timeline for 'done'. When the majority of people had that expectation, it seemed to work decently. In 25 years of professional work, that's the only place I can remember seeing it done that disciplined. And... they were only around 100 folks total - not sure it could necessarily scale as they grew.
henrik_w 7y ago
I agree with keeping notes for yourself. I think the key benefit is from writing the notes more than the resulting document. The act of writing it down helps you learn/remember the lessons I think. I have been keeping records of the trickiest bugs I have come across for over 15 years [1]. I believe this has helped me internalize the lessons I wanted to learn from them, so I (mostly) won't repeat them. Also, when you leave the company you keep your own notes. [1] https://henrikwarne.com/2016/06/16/18-lessons-from-13-years-of-tricky-bugs/ https://henrikwarne.com/2016/06/16/18-lessons-from-13-years-...
- happywolf 7y ago
  Nice sharing. Like the tip on 'Own Tools' that has been applied in numerous situations. Sometimes a quick-and-dirty script(usually bash or python) will accelerate things considerably.
toast0 7y ago
Adding on, when I've worked where people ask for the wikis to be updated, I've found that nobody reads the documents I have written. Honestly, keeping documentation up to date, and writing accessible documentation is a different job than making the system. If it's important, you need a technical writer on staff to do it, and a commitment that developers need to work with the writer to get things accurate and as complete as possible. It's the same as testing; you can try to make developers do it, but some developers aren't capable of good testing and some aren't capable of good writing, and in both cases, having an independent person doing the work will result in more coverage, since the other person may not share the same "implicit" ideas that the one developer might not document or test.

kqr 7y ago

This is realism, not pessimism. The reason employee retention is so important for software companies (or at least should be!) is that the loss of knowledge associated with replacing one employee is much greater than at first glance. (Well, that and the fact that some things have really long feedback cycles, and you have to stick around for a few years to truly see the consequences of your decisions.)

HalfYawn 7y ago

Behind every sign there's a story :)