To be honest I was expecting the article to focus primarily on internal docs, meetings, long Slack posts, etc. Staff engineers spend a relatively small percentage of their time writing code. A lot of what it takes to be successful is knowing how to communicate with different audiences which AI should be really useful for.
And do you go back and update all documents whenever something changes? If you’re swapping people around every month I agree that you must keep everything written down, happens a lot in projects that bring consultants in. But if you have a core team of people and you get 2-3 new people per year then you should be more relaxed about it.
I strongly believe that proactively keep documentation up to date is not worth the effort.
Here is what I recommend in my teams:
- There’s an onboarding guide that is usually only updated when new people onboard. If something is not right they raise it and their onboarding partner fixes it.
- When someone shares a technical document/RFC we add it to a central repository with a creation date on it. These are point in time and usually not updated but still useful for new hires.
- We sometimes do onboarding sessions to walk through the architecture, these are recorded and added to the central information repository.
Note that in the things I wrote above there’s a mix of up to date content and slightly outdated content, ultimately the code is the source of truth. It’s not worth spending time writing docs that no one is gonna read.
Face to face communication is very underrated nowadays, probably because of the negative connotations associated with meetings. Talking to someone is by far the fastest way to convey information. I often prefer a quick chat than spending 30 minutes writing Slack messages back and forth. I agree that writing has other benefits and it's better in certain cases but we need to get out of the mindset that writing/async is always better.