5 ms·

> critically important pieces of institutional knowledge are missing And the guys who have it are the "10x devs" in that joint. >Or they find it "boring". Or

> critically important pieces of institutional knowledge are missing And the guys who have it are the "10x devs" in that joint. >Or they find it "boring". Or, it doesn't count much towards your annual performance review so then why bother if you have enough stuff on your plate that does count towards your performance review. When was the last time someone got promoted because they write really, really good internal documentation? Let's face it, most web facing SW nowadays is like fast-food. Investing tons of time in writing quality documentation would by like a triple Michelin star chef writing a 20 page article about a doner kebab.

pdimitar 6y ago
> Or, it doesn't count much towards your performance review Oh I agree that most managers have no clue about this metric so doing it well will likely mark you as the slowpoke of the team. The way I address this is that I budget the time for those "extra" activities beforehand. I just find it a professional courtesy to leave good docs for the next person after me -- or new hires while I am still there. Not sure there's a way to actually incentivize programmers to write good docs.
- tlarkworthy 6y ago
  It would help if people read them. I write good docs and I often wonder why, as I have to endless redirect inbound queries to the doc. It's ok for my team, they learn, but it's annoying that the whole org never reads anything.
  - pdimitar 6y ago
    I am one of the guys who appreciates docs but also wants pointers at the start. Just giving me an URL with 50-100 pages of docs is not good enough. Give me something like "when you are just starting", "when you want to tackle a ticket involving X" or "when you need to edit the deployment script" etc. In my last job the architect was always irritated with me because he wrote a bunch of docs but never organized them or just gave a proper small index -- seriously, just 15 lines of text with links so you know where to click at the start would have been enough! -- but then somehow the team was at fault for "not reading the docs". So there's a balance. I don't appreciate being given a book and being told "figure it out", which is what happened in my last jobs. Sigh. Having a small page with starting pointers I always found priceless and is what I do in my work and I've had people contacting me 5 years after I left the job to thank me for it.
    - tlarkworthy 6y ago
      my docs are a single page full of one liners for practical issues that have organically arisen several times over the years, with a table of contents at the front. As I said, I write good docs, but no-one will read them until they have been caught out 3 times asking obvious questions had they gone to the doc first. If I am not around, I know the docs will be abandoned immediately despite it representing a tome of hard won knowledge that saves an incredible amount of aggregate time from never needing to figure out how to do the same task twice.
  - loopz 6y ago
    There should exist a need, for pouring labour into something, to make it worthwhile. Also, when the need is there, it is much clearer for who and what purposes you're providing knowledge. It's not laziness if it's efficiency, or love.
deleted 6y ago
[deleted]
TeMPOraL 6y ago
> Let's face it, most web facing SW nowadays is like fast-food. Investing tons of time in writing quality documentation would by like a triple Michelin star chef writing a 20 page article about a doner kebab. A lot depends on the project size and expected lifetime (honest expected lifetime). But you can look at it from another perspective: the most basic internal documentation, like commit messages explaining why something was done, interface-level comments explaining what a function or class does, internal comments explaining the tricky bits of implementation - they all increase velocity of product development. So it's a good thing to do on team level. (But it's kind of a "pay it forward" thing. You may not benefit much from your own comments, but you'll be thankful for the ones your co-workers leave.)

pdimitar 6y ago

> Or, it doesn't count much towards your performance review Oh I agree that most managers have no clue about this metric so doing it well will likely mark you as the slowpoke of the team. The way I address this is that I budget the time for those "extra" activities beforehand. I just find it a professional courtesy to leave good docs for the next person after me -- or new hires while I am still there. Not sure there's a way to actually incentivize programmers to write good docs.

tlarkworthy 6y ago
It would help if people read them. I write good docs and I often wonder why, as I have to endless redirect inbound queries to the doc. It's ok for my team, they learn, but it's annoying that the whole org never reads anything.
- pdimitar 6y ago
  I am one of the guys who appreciates docs but also wants pointers at the start. Just giving me an URL with 50-100 pages of docs is not good enough. Give me something like "when you are just starting", "when you want to tackle a ticket involving X" or "when you need to edit the deployment script" etc. In my last job the architect was always irritated with me because he wrote a bunch of docs but never organized them or just gave a proper small index -- seriously, just 15 lines of text with links so you know where to click at the start would have been enough! -- but then somehow the team was at fault for "not reading the docs". So there's a balance. I don't appreciate being given a book and being told "figure it out", which is what happened in my last jobs. Sigh. Having a small page with starting pointers I always found priceless and is what I do in my work and I've had people contacting me 5 years after I left the job to thank me for it.
  - tlarkworthy 6y ago
    my docs are a single page full of one liners for practical issues that have organically arisen several times over the years, with a table of contents at the front. As I said, I write good docs, but no-one will read them until they have been caught out 3 times asking obvious questions had they gone to the doc first. If I am not around, I know the docs will be abandoned immediately despite it representing a tome of hard won knowledge that saves an incredible amount of aggregate time from never needing to figure out how to do the same task twice.
- loopz 6y ago
  There should exist a need, for pouring labour into something, to make it worthwhile. Also, when the need is there, it is much clearer for who and what purposes you're providing knowledge. It's not laziness if it's efficiency, or love.

deleted 6y ago

[deleted]

TeMPOraL 6y ago

> Let's face it, most web facing SW nowadays is like fast-food. Investing tons of time in writing quality documentation would by like a triple Michelin star chef writing a 20 page article about a doner kebab. A lot depends on the project size and expected lifetime (honest expected lifetime). But you can look at it from another perspective: the most basic internal documentation, like commit messages explaining why something was done, interface-level comments explaining what a function or class does, internal comments explaining the tricky bits of implementation - they all increase velocity of product development. So it's a good thing to do on team level. (But it's kind of a "pay it forward" thing. You may not benefit much from your own comments, but you'll be thankful for the ones your co-workers leave.)