5 ms·

It's bloody hard, you say? Hm, maybe in part of the cases, but you know what else is even harder? Getting onboarded in a new project and having zero clue why X

It's bloody hard, you say? Hm, maybe in part of the cases, but you know what else is even harder? Getting onboarded in a new project and having zero clue why X is written like that, why is Y is where it is and why Z is using a 10-year old thread-pool scheduler that is grossly inefficient. And you have to deliver feature A and bugfix B and you might collapse the house of cards and of course, critically important pieces of institutional knowledge are missing. Eventually you do find out everything you need since you're not dumb and are a bright programmer, but you've lost weeks or maybe even months. The business have lost money because they basically had to give you anywhere from 1 to 3 full salaries just so you can catch up. And it's not even your fault, it's the last person's. So I can't sympathize with "it's hard" at all. So what, dude? It's part of your job. Do it well. Nobody hired you to only do the easy stuff. But this does outline the somewhat introverted, almost autistic nature of many programmers. When it comes to writing good docs most of them give up because that requires good and clear articulation which they don't possess. Or they find it "boring". But they'd still curse if they found an obscure GitHub repo that could help with their their niche problem and find out that it has zero explanations or code comments.

rapnie 6y ago
I guess indeed many find it bloody boring. A chore to be dodged if possible. And also when doing some documentation work, because people are so deeply into the subject matter, they feel many things are obvious and need no further elaboration.
- pdimitar 6y ago
  Yep, and that's why being sympathetic and able to put yourself in the shoes of an outside reader are very important soft skills for a programmer.
ChuckNorris89 6y ago
> 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.
__jem 6y ago
This is harsh, but I largely agree. I think the issue is that you often weren't hired to write docs either... biz often only cares about new features. It's not the writing docs is hard, but that it takes a lot of time. I can write great docs, but it easily takes 50% of my time relative to code. The quality falls off pretty hard too -- my half-effort docs are pretty bad, like maybe worthless? Obviously, there's a baseline level of, like, just commenting code which some devs still complain about, and that's absurd. But I think we need to be better at getting other people to value docs if we want them to be written, because they take time and effort to produce, it's a tradeoff like anything else in building software.
- pdimitar 6y ago
  IMO the only way to achieve that is to inform the business about it. If they are aware that knowledge is being lost and then has to be re-acquired by the next person then I think that a lot of business people immediately grok the idea that not writing docs is a liability and a risk and that it makes swapping people hugely expensive (indirectly, due to you being paid just to catch up for a while). Businessmen get this stuff quite well. But I feel very often nobody explains them the situation.
  - __jem 6y ago
    Yeah, I agree that business people are often quite receptive when you lay it out in terms of economic impact. I agree that this is a skill all devs should work on -- even just being able to talk about orders of magnitude of $ in your estimates is incredibly helpful. But I've often found other devs can be your worst enemy here -- they rely on esoteric knowledge to build defensible moats around their seniority. Harder to convince execs about firing their "star" 10xer. Ultimately, this is why I think we need compiler assistance so that stuff like docs can be enforced in CI unilaterally.
    - pdimitar 6y ago
      > they rely on esoteric knowledge to build defensible moats around their seniority Sadly you are correct. Job security and thus gatekeeping are the higher priority. So yeah, yet another case of perverse incentives. :( > Ultimately, this is why I think we need compiler assistance so that stuff like docs can be enforced in CI unilaterally. Completely agreed, plus declarative programming. At 41 I am already sick to my stomach about having to manually write boilerplate. Tooling helps only a little and is hugely overrated; so what if the tool generates skeleton controllers et. al.? 90% of what you know should be there is yours to do anyway. But that's a huge tangent. :)
Someone 6y ago
I think the solution is the land where documentation is part of the code, so that you have to write it. Ada workbenches tried to get there, as did UML workbenches, but failed. Lisp and Smalltalk somewhat succeeded, but only for single user systems. Two questions remain: Firstly, does that land exist? Secondly: if so, how do we get there from out local optimum that many, many programmers spend decades on to build higher and higher?
TeMPOraL 6y ago
> having zero clue why X is written like that, why is Y is where it is and why Z is using a 10-year old thread-pool scheduler that is grossly inefficient. And you have to deliver feature A and bugfix B and you might collapse the house of cards and of course, critically important pieces of institutional knowledge are missing. I've already resigned to the fact that any changes in the codebases I tend to work on involves spelunking through past commits, trying to git-blame my way into knowing where some suspect feature came from (and thus who to ask to explain it to me). But few things annoy me more than when, after an hour of poking around and following code being moved across files, I finally arrive at the commit that introduced the thing I'm after, only to discover that the entire commit message is "refactored $foo", or "fix $blah". Oh, and the commit touched 20 different files, implementing 3-5 different things, and the author left the company a year ago. So if you aren't doing it already, then for the sake of everyone (including yourself few months from now): please, write descriptive commit messages, while everything is still fresh in your memory. By descriptive, I mean at least a bullet point list of everything that was changed, and why. Even if it means repeating some of the stuff from a ticket or a discussion somewhere - because none of these things will be available or easy to find few months later. Something like: Add feature Foo This commit implements feature Foo, as per ticket #12345: option $foo controls whether or not Flux blergs or blargs; in the latter case, $this and $that will happen. * Configuration files have been updated with the new paramter. * Flux Controller no longer looks at unobtanium to determine the type of blerging to perform. * The above implies that checking Flux for the type of blerg is now speculative, and should not be relied on in the future. * A new utility Asdf has been added; it provides common functionality for blarging. ... Etc. You get the picture. It's quite easy to write a message like this when committing - it's essentially a polished brain dump. And its usefulness will be immense the next time someone has to work in this part of the codebase.
- truetraveller 6y ago
  Hey, nice commit template. Will be using something like this. Thanks!
- pdimitar 6y ago
  I do that for big commits. But usually I prefer much smaller commits whose 1-2 lines of text are enough. I reserve those bigger texts for PR descriptions. I found those to be a nice balance, most of the time.

rapnie 6y ago

I guess indeed many find it bloody boring. A chore to be dodged if possible. And also when doing some documentation work, because people are so deeply into the subject matter, they feel many things are obvious and need no further elaboration.

pdimitar 6y ago
Yep, and that's why being sympathetic and able to put yourself in the shoes of an outside reader are very important soft skills for a programmer.

ChuckNorris89 6y ago

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

__jem 6y ago

This is harsh, but I largely agree. I think the issue is that you often weren't hired to write docs either... biz often only cares about new features. It's not the writing docs is hard, but that it takes a lot of time. I can write great docs, but it easily takes 50% of my time relative to code. The quality falls off pretty hard too -- my half-effort docs are pretty bad, like maybe worthless? Obviously, there's a baseline level of, like, just commenting code which some devs still complain about, and that's absurd. But I think we need to be better at getting other people to value docs if we want them to be written, because they take time and effort to produce, it's a tradeoff like anything else in building software.

pdimitar 6y ago
IMO the only way to achieve that is to inform the business about it. If they are aware that knowledge is being lost and then has to be re-acquired by the next person then I think that a lot of business people immediately grok the idea that not writing docs is a liability and a risk and that it makes swapping people hugely expensive (indirectly, due to you being paid just to catch up for a while). Businessmen get this stuff quite well. But I feel very often nobody explains them the situation.
- __jem 6y ago
  Yeah, I agree that business people are often quite receptive when you lay it out in terms of economic impact. I agree that this is a skill all devs should work on -- even just being able to talk about orders of magnitude of $ in your estimates is incredibly helpful. But I've often found other devs can be your worst enemy here -- they rely on esoteric knowledge to build defensible moats around their seniority. Harder to convince execs about firing their "star" 10xer. Ultimately, this is why I think we need compiler assistance so that stuff like docs can be enforced in CI unilaterally.
  - pdimitar 6y ago
    > they rely on esoteric knowledge to build defensible moats around their seniority Sadly you are correct. Job security and thus gatekeeping are the higher priority. So yeah, yet another case of perverse incentives. :( > Ultimately, this is why I think we need compiler assistance so that stuff like docs can be enforced in CI unilaterally. Completely agreed, plus declarative programming. At 41 I am already sick to my stomach about having to manually write boilerplate. Tooling helps only a little and is hugely overrated; so what if the tool generates skeleton controllers et. al.? 90% of what you know should be there is yours to do anyway. But that's a huge tangent. :)

Someone 6y ago

I think the solution is the land where documentation is part of the code, so that you have to write it. Ada workbenches tried to get there, as did UML workbenches, but failed. Lisp and Smalltalk somewhat succeeded, but only for single user systems. Two questions remain: Firstly, does that land exist? Secondly: if so, how do we get there from out local optimum that many, many programmers spend decades on to build higher and higher?

TeMPOraL 6y ago

> having zero clue why X is written like that, why is Y is where it is and why Z is using a 10-year old thread-pool scheduler that is grossly inefficient. And you have to deliver feature A and bugfix B and you might collapse the house of cards and of course, critically important pieces of institutional knowledge are missing. I've already resigned to the fact that any changes in the codebases I tend to work on involves spelunking through past commits, trying to git-blame my way into knowing where some suspect feature came from (and thus who to ask to explain it to me). But few things annoy me more than when, after an hour of poking around and following code being moved across files, I finally arrive at the commit that introduced the thing I'm after, only to discover that the entire commit message is "refactored $foo", or "fix $blah". Oh, and the commit touched 20 different files, implementing 3-5 different things, and the author left the company a year ago. So if you aren't doing it already, then for the sake of everyone (including yourself few months from now): please, write descriptive commit messages, while everything is still fresh in your memory. By descriptive, I mean at least a bullet point list of everything that was changed, and why. Even if it means repeating some of the stuff from a ticket or a discussion somewhere - because none of these things will be available or easy to find few months later. Something like: Add feature Foo This commit implements feature Foo, as per ticket #12345: option $foo controls whether or not Flux blergs or blargs; in the latter case, $this and $that will happen. * Configuration files have been updated with the new paramter. * Flux Controller no longer looks at unobtanium to determine the type of blerging to perform. * The above implies that checking Flux for the type of blerg is now speculative, and should not be relied on in the future. * A new utility Asdf has been added; it provides common functionality for blarging. ... Etc. You get the picture. It's quite easy to write a message like this when committing - it's essentially a polished brain dump. And its usefulness will be immense the next time someone has to work in this part of the codebase.

truetraveller 6y ago
Hey, nice commit template. Will be using something like this. Thanks!
pdimitar 6y ago
I do that for big commits. But usually I prefer much smaller commits whose 1-2 lines of text are enough. I reserve those bigger texts for PR descriptions. I found those to be a nice balance, most of the time.