The other thing about documentation is that it inevitably goes stale.

So the question becomes: is no documentation better or documentation that can be - potentially - entirely out of date, misleading or subtly wrong, because eg they documented the desired behavior vs actual behavior (or vice versa).

I'm generally pro documentation, I'm just fully aware that internal documentation the devs need to write themselves and for themselves... Very rarely gets treated with enough respect to be trustworthy.

So what it comes down to is one person spearheading the efforts for docs while the rest of the team constantly "forgets" it, until they decide it's not worth the effort as soon as the driving force either changes teams or gave up themself.

  > How does the saying go, something like “show me the incentives and I’ll show you the outcome?”

Of course, the issue is time. What timeframe are we measuring the incentives at.

You should pay current employees less iff either 1) time doesn't exist (or you are finding the instantaneous optimal solution) or 2) employees are fungible (institutional knowledge does not exist)

Otherwise, you should be trying harder to keep current employees because you recognize the value of institutional knowledge. You don't have to train current employees. Current employers don't have to get up to speed (which usually take a few months and can take years).

It's not a hard equation

  Costs:

  Existing employee: 
    +cost of raise

  New employee: 
    +salary of existing employee
    + raise
    - onboarding inefficiency * (t_n - t_0)
    - existing employee * (time they train)
    - costs to interview, hire, etc * (time to hire new person)

  > the best way to fix the damage from footguns be by preventing the damage to you in the first place by not being there if/when it goes off?

My argument is that the best strategy is to ,,never fire'' the footgun.

Avhception gives a good visual analogy without using the word footgun[0]

[0] https://news.ycombinator.com/item?id=44744167

There is a hack for that: write the comments before and/or as you write the code. When things are still unclear, weird. Of course do a final pass on them to ensure that they are correct and useful in the end. This is one example of document as-you-go, instead of doing it after "the work" is done. I find it generally leads to better outcomes. Doing documenting only at the end is in many ways the worst way to do it.

Here's my method, which is a bit similar to the siblings.

Your first "docs" are your initial sketch. The pieces of paper, whiteboard, or whatever you used to formulate your design. I then usually write code "3" times. The first is the hack time. If in a scripting language like python, test your functions in the interpreter, isolated. Then "write" 2 is bringing into the code, and it is a good idea to add comments here. You'll usually catch some small things here. Write the docstrings now, which is your 2nd docs and your first "official" ones. While writing those I usually realize some ways I can make my code better. If in a rush, I write these down inside the docstring with a "TODO". When not rushing I'll do my 3rd "write" and make those improvements (realistically this is usually doing some and leaving TODOs).

This isn't full documentation, but at least what I'd call "developer docs". The reason I do things this way is that it helps me stay in the flow state, but allows me to move relatively fast while minimizing tech debt. It is always best to write docs while everything is fresh in your mind. What's obvious today isn't always obvious tomorrow. Hell, it isn't always obvious after lunch! This method also helps remind me to keep my code flexible and containerize functions.

Then code reviews help you see other viewpoints and things you possibly missed. You can build a culture here where during review TODOs and other similar things can be added to internal docs so even if triaged the knowledge isn't completely lost.

Method isn't immutable though. You have to adapt to the situation at the time, but I think this is a good guideline. It probably sounds more cumbersome than it is, but I promise that second and third write are very cheap[0]. It just sounds like a lot because I'm mentioning every step[1]

[0] Even though I use vim, you can run code that's in the working file, like cells. So "write 2" kinda disappears, but you still have to do the cleanup here so that's "write 2"

[1] Flossing your teeth also sounds like a lot of work if you break it down into all subtasks 1) find floss, 2) reach for floss, 3) open floss container, ...

It's a good visual story to describe something we all frequently do. We often create our own anxiety.

It's easy to hear "let's slow down a little" as "don't move fast" but it's wrong to interpret that because "slow down" is relative. There is such a thing as "too fast". You want to hear "slow down" just as much as you want you great calls to speed up. When you hear both you should be riding that line of fast but not too fast. It's also good to make sure you have a clear direction. No use in getting nowhere faster.

I'll use another visual analogy. Let's say you and I have a race around the world. I take off running, you move to the drawing board. I laugh as I'm miles ahead, and you go to your workshop, which is in the other direction. The news picks up our little race, and laughs at you as I have such a tremendous lead. I'm half way done, but you come out of your workshop having build a jet. I only get a few more miles before you win the race. The news then laughs at my stupidity and your cleverness, as if it was so obvious all along.

Sometimes to move fast you need to slow down. It takes lots of planning and strategizing to move at extraordinary speeds.

Yep. I feel like this every time a coworker pushes back on a code review “I’m just trying to get this to work”.

Okay but this is the ninth time in a row, and now you’re building on top of all the other half-baked bits, and the confusion from every one of these layering on top of one another is forcing you to do more hacks on hacks on hacks. And then when you finally “get it to work” there will be no way to disentangle this whole mess.

I disagree (a bit). It really depends on the person. I've know a good number of scientists who are great mathematicians but get confused as soon as they see code.

My point is that everyone is different. Documentation isn't just for developers and you never know who's going to contribute. It is also beneficial to have multiple formats just because even with a single person different ways make more sense on one day than the next. Having different vantage points is good to have. It is also good to practice your own mental flexibility[0]

I think the pytorch docs are a good example here. Check out the linalg module[1] (maybe skip the matrix properties section).

[0] This will also help you in the workplace to better communicate with others as well as makes you a better problem solver. Helps you better generalize ideas.

[1] https://docs.pytorch.org/docs/stable/linalg.html

> should also be caught in code reviews

Assuming they even have code reviews - in your experience, in a situation where the person writing the code didn't check if it already exists, the reviewer will check that and then tell them to delete their already finished implementation and use that existing thing?

I wouldn't say you should explicitly check, necessarily. More like, you go to implement the widget and when you open the appropriate file to get started, it's already there.