4 ms·

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

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.