Documentation is one of those things that every developer will praise in a conversation while probably not doing enough of it, if any. We’ve all heard a million reasons why documentation is good. It helps with knowledge transfer so everyone is on the same page. It saves the new guy from being totally lost in the woods and needing to pester all the other developers to braindump their knowledge through audible conversation. It saves your future self from cursing your past self. Documentation is the holy text that keeps teams lubricated and spinning.
But even though we all largely agree about the benefits of documentation, few teams actually devote meaningful time to doing it. It falls to the wayside. There’s so much actual code to write, so many fires to extinguish, so many deadlines to miss. So how do you get your team to invest in writing more documentation? You trick them.
My Team
I’m a developer at Activision Blizzard on the Call of Duty Companion App. We’re a pretty small and tight knit team. I believe I’ve figured out a way to get my team to write a lot of documentation. And I believe that these tips on how I did it can be applied to any team. A few months ago we were investing almost no time into documenting things. Now we spend a lot of time documenting things.
But before I explain how we got to that point, here is the most important thing not to do. Don’t boss people around. I have never been a believer in telling your peers what to do. Real change happens on a more authentic and organic level. So it is important to understand that statements like “you should write more documentation” definitely won’t work. Behavior doesn’t change at a wand wave. Your fellow developers plates are already full with Thanksgiving sized heaps of other tasks and responsibilities so we need a better solution than making demands.
Phase 1: Doing It
So how did I actually get my team onto the documentation bandwagon and pumping out tons of legitimately useful docs? It’s simple. I started writing documentation.
You have to be the first person to step up and write great documentation. Once you do you now have a team writing documentation. Even if it’s just one person so far. You should be writing documentation as you go too. It needs to be a part of your routine anytime you fix something, setup a new process, build a new feature, or whatever else may be worthy of being documented.
Okay, but now you’re thinking “how do you get the rest of the team to write documentation? Isn’t that what this is all about?” Here are the next steps you need to trick everyone else into doing it too.
Phase 2: Broadcasting That You’re Doing It
Congratulations. Now you’re actually writing documentation. And you’re doing it every time it makes sense to. This is a critical foundation for tricking everyone else into doing it. Now you need to start broadcasting that you are writing documentation.
Anytime you write a new wiki article or document something you need to gently let everyone know. Note the word “gently”. Remember the goals of good docs are team cohesion and improved output. So your words should reflect this. “I just wrote this wiki page for feature X that I just built. It tells you everything you need to know to start using it too. Please let me know if you think I missed anything.”
You’ve now broadcasting that you are writing documentation and planted the seed that this is something your peers can do too. They are going to see the value in writing documentation because they are going to pop open your wiki page for feature X and quickly get up to speed about what feature X does. You have empowered them. And if there is four people on the team then you have empowered all four of them.
Phase 3: Let Others Know When It Would Be Useful To Do It
Now that you’ve started to broadcast that you write documentation, you can look for opportunities to suggest that they write documentation. Did another team member just finish building feature Y? Or did they invent a new plan for building the Xcode project that doesn’t cause that weird bug? Did they do anything at all that made you think, “wow I have zero idea how to do that and it would be really useful if the team and I knew how to do it too”? These are the moments you can gently suggest they write some docs. “Hey, that new feature is super useful! Would you be willing to take some time and write something up about it please?”
Most likely the first several times you suggest documenting they won’t do it. That’s normal and okay. There’s no need to pester. In fact, pestering or reiterating you want something specific documented just feels like you are trying to put food on their already full plate. But stay consistent. Anytime something worthy of documentation appears just continue using the strategy of letting them know how helpful it would be if they documented it. If they do document something then make sure to express appreciation.
Phase 4: Reminding Others That You Did It
Here’s where I think the most powerful convincing happens. This is the thing that will actually get your team members to write documentation too. Make sure to refer to your documentation as often as possible. If someone asks you, “how do I do X again?”, then you should be able to point them toward documentation about it. If you are staying resolute about writing documentation as you go then these opportunities will definitely pop up. Don’t be a jerk about it though. First you should actually address their question as if the documentation didn't exist. Just linking them to a doc might come off as rude or passive aggressive. Help your peer and afterward politely mention something like, “hey by the way, here’s where to find this information in our documentation in case you need it later.”
The Results
So maybe all of this isn’t necessarily trickery but that’s more fun to say than “setting a good example that politely demonstrates the value of good documentation”. If you keep up these four strategies (write docs consistently, broadcast when you do, suggest when others could write docs, and refer to existing docs when possible) then I know you will eventually get traction and the rest of your team will start writing more documentation. It will start as a trickle and domino into an avalanche
On the Call of Duty Companion App team, it started with me documenting simple things like our style guide or information about our push notification capabilities. I stuck to my method and then one day my team lead created a gif on how to configure settings in Xcode with some written instructions in an internal wiki article. The trickle had begun. After that another developer started documenting components with screenshots and breakdowns of how to use them throughout our app. Now we’re all writing documentation regularly. Our documentation is helping us all be on the same page. We are seeing it speed up our development process. And now any time we have a brain 404 where we don’t remember how to do something, we aren’t bumbling through the woods again wasting time re-figuring it out. It’s all there in our documentation.
If you're looking to achieve similar results, all you need to do is trick a few people.
Top comments (5)
Great article.
I believe in a team, leading by example works the best. This way you earn respect and people genuinely do things because they really want to do a job. As opposed to writing very bad documentation when a person is forced to do so.
I honestly thought it was really a nasty trick.🤣 Nevertheless, nice advice!
Am I only have a feeling that that article - medium.com/level-up-web/how-to-mak... - is a rewriting of this one?
Nice post btw 🙂
LOL! Hopefully a case of great minds thinking alike. ☠️
Nice! Enjoyed reading this. Thank you.