2 ms·
> Documentation and written processes for everything. There are upsides and downsides to this. Foster a culture of 'document everything', and you'll quickly
by londons_explore 4y ago
> Documentation and written processes for everything.
There are upsides and downsides to this. Foster a culture of 'document everything', and you'll quickly end up with a corporation which runs like molasses as everyone has to spend time writing up meeting minutes and spends 90% of their time updating documentation and arguing over if something is allowed within the XYZ procedure.
In my orgs, I generally say "a 1 pager quickstart guide on how each subsystem works, and everything else is docstrings and comments in the code".
If the system is too complex for that to be enough for a new engineer to understand whats going on, then your system should be redesigned to be simpler. We're designing apps and web services. If it's complicated, then you're doing it wrong.
- Aeolun 4y ago> If it's complicated, then you're doing it wrong. You still need to do something even if you know this. Replacing the system is not an option, since the next one will be just as bad.
- londons_explore 4y agoNormally an overly complicated system is the result of: * evolving requirements over time (a rewrite fixes this) * A tech lead overcomplicating things for job security or to justify expanding the team or a promotion. This is rarely easy to fix, because typically now things will depend on crazy complex semantics... "We extended our pubsub system into a probabilistically lossy data caching layer!" I normally fix it by moving the project to 'maintenance mode' and reducing headcount to 0.5 or so. Obviously it's best to have enough oversight that that kind of thing doesn't happen in the first place.