You might have noticed that I did not share my blog post yesterday. I recently received an education on how to LinkedIn better, and part of that process is experimentation. I am not doing this to try to induce you to buy some Affiliate-fee-collecting Amazon items, but if you are going to buy anything, it should be a portable monitor like this one. Normally, someone posts a link because they endorse it, but I know better. Maybe one of you will be momentarily piqued and buy it because no one talks about portable monitors, and you can tell me if it’s a useful product or not. Twice a year, or slightly more, I find myself in a hotel room wishing I had a second monitor for my laptop. It is almost frequent enough that I would drop about two hundy on solving this problem. A personal recommendation from one of you super smart people would go a long way to make me click. Is that not the most bullshit sales pitch you ever heard? It’s like I am using psychology to reverse-recommend something to you.
I intentionally made us all feel collectively dumber. Today, I want to talk to you about something that requires you to feel less intelligent: your company’s internal wiki page.
I am as angry at the word wiki today as I was when I first heard it during the War of 1812. It is a dumb word, and you will be worse than disappointed if you Google its Origin Story. I got used to Yahoo and Google. I even accepted the word Zune, if only out of spite for the word podcast. When I drew the line of acceptable technology words, wiki landed on the other side. The sad part is that while wiki is such a ridiculous word, it does belong to an item of serious importance to your company’s long-term growth and success.
Let’s step backward about fifteen years. A bright-eyed and bushy-tailed John Szeder has just become VP of Engineering at hi5.com. The company is several years old, and stuff is breaking in production. I have to give the engineering team credit here. They were excellent at applying tape, glue, and rubber bands to keep this website hurtling forward in time. I would frequently attempt to understand some of the more arcane fixes we had to put into production and wander around on the company’s internal wiki and the comments in the code repos to learn more about what was built and who was responsible for it.
Random polling from some of the longest-tenured engineers yielded significant shrugs when I asked them if they worked with some of the authors of the ancient features. I had never worked in a code base before that was old enough to attend public school. The notion of source code archaeology was novel to me then.
We can fast-forward significantly to today. Between then and now, I had a tour of duty at Zynga and repeatedly had the opportunity to see an old legacy system in production. It is interesting to see an old-old codebase with half a dozen eras of engineering resignations wrapped around it like tree rings from big forest fires. It teaches you to respect documentation.
Every time you join a team working on an existing product, you will add a little more to your own respect for documentation. Each README file is its own little exhibit. Each wiki page is a document for archivists to pore over and contemplate when its wisdom is called on.
You want to be careful when you are working on a product, and someone tells you, “Let’s have a meeting to go over your onboarding; the documentation is out of date,” or your product manager wants to gather you around the campfire late at night to regale you with tales of functionality. We do not call them user stories because we transmit them orally, like the bardic lore of the Middle Ages, so let’s not treat them that way.
The best-performing businesses do a very good job of recording their traditions and thinking in the form of documentation. As dumb as I think the word wiki is, I value the need to turn folklore into fact.
When someone joins a team and is instructed to follow the onboarding documentation, I always include an important addendum: “If this document is outdated, please update it. It is important to leave it better than you found it.” The next person through will thank you for it, trust me.
I think about this quite a bit as I write my blog. I also think about it when I hear game companies discuss their best practices. I am excited by some of the work we are doing at Game Data Pros because we are creating many interesting tools and processes to help companies succeed. An artifact of some of these new tools and processes is how well they are formalized.
Internal documentation, customer documentation, best practices, everything. The more things you write down, the better off you will be.
I’ll see you next week, possibly on Tuesday. I reserve the right to do some tuning over the rest of the summer as my profile becomes increasingly impressionable.
