At a point in my past I’ve found myself working in a somewhat successful startup, it seemed successful because we were hiring more and more engineers and the scope of work and number of teams kept steadily increasing. Somewhere in the middle I realised our engineering staff needed a set of engineering principles and a progression framework that would act as a north star for my fellow team members to follow describing how to navigate the chaotic theatre of war that is a start up tech company.
I’ve set down a goal to myself to inscribe a complete guide for our team to not only excel in their roles but also advance themselves and improve. It felt like a monumental task but one that would pay off greatly for the team, and the company. I took this project on with great enthusiasm. I poured my knowledge into the document, covering every nook and cranny I could think of. Whether it was how to handle edge cases, best practices for problem solving and collaboration. I wanted these documents one to rule them all, to be a one-stop resource for developers so that no matter what situation they found themselves in, they could turn to these guides and find the answers they needed.
Few weeks later, I had produced a comprehensive, thorough… and entirely unreadable wall of text that even I thought it was to difficult to follow and that should have been a red flag. It was the kind of thing you’d look at, drop a like on the Confluence page and then never open again. I should have taken a hint from the fact that Moses used a couple of stone tablets and a chisel to write down rules for our entire society and I should have scraped it then and there but I didn’t, the effort I put into it made me blind to the fact that reading these documents was more of an endurance test than a helpful guide. The problem was that I had mistaken detail for effectiveness.