> Still I don't recall design docs being important enough to matter for a promotion by themselves. Promos were supposed to be about overall impact, not production of specific artifacts.
How can you prove "impact" to a committee who otherwise doesn't know your work, without providing evidence in the form of docs, code examples, and other artifacts?
Yes the most common complaint about any incentive system that rewards "impact" is that it's hard to demonstrate for some kinds of jobs. I started in SRE ("devops") and then later moved to anti spam and security, so had to find alternate ways to demonstrate impact.
Still, the intuition is obvious enough. If you don't tie incentives to some sort of verifiable impact on the business then a lot of people end up doing make-work in which the appearance of doing work substitutes for actually being useful. As this wider thread is complaining about, in fact.
A common form of this complaint can be found in any business that makes software, that refactoring or "tech debt" style work is hard to justify via business oriented metrics. There's some truth to that, but also I came to feel that forcing people to find some sort of business-related metric they're affecting helps keep engineers honest. When to take on and when to pay down tech debt is one of the most nuanced and difficult subjects for any engineer to learn on their path to seniority, and becoming obsessed with refactoring is one of the most common failure modes along the way. Saying "but how did this actually affect the business" forces a reality check that can help avoid doomed rewrites and other pathologies.
For example, Google has a system that automatically finds and deletes dead code. This is the sort of thing that at first seems hard to justify, but with a bit of work you can do it. Work out the overall eng cost of maintaining each line of code (some napkin calculations are fine), work out how much code you're able to delete, work out the cost of developing the auto-deleter system, show that money spent on maintenance of dead code > cost of developing the system. Business impact demonstrated, done.
It doesn't have to be monetary either. I never demonstrated monetary impact. It was all things like "contributed to the launch of X that increased traffic by Y". In the case of the security and antispam work it was "successfully blocked Z attacks against our users", stuff like that. The impact is obvious even if not expressed in dollar terms.
How can you prove "impact" to a committee who otherwise doesn't know your work, without providing evidence in the form of docs, code examples, and other artifacts?