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.