[jjgreen]

Don't have technical documentation -- instead have

- design documentation which has a date, and it is understood that it is correct at the time of writing but will age and become less accurate with time

- clear code with comments on the sharp corners

[ardalanpouya]

How is design docs different from technical docs?

[Double_a_92]

Design docs are for the developpers. Technical docs could also be for the users, by e.g. ending up in some manual or so.

[ardalanpouya]

Sorry. In that case I used a bad word. I probably should have said internal docs that explain some specific flow or behavior of the system. A good example is one that onboards new devs.

[jjgreen]

They are not updated, on purpose. This is the design now.

[ardalanpouya]

Is that ideal for example for onboarding new developers? Our challenge is we are are starting to hire but we also move very fast and every time we refer people to our onboarding docs, they come back confused because some essential thing is now deprecated.

[jjgreen]

Hence clear code with comments on the sharp corners