OSU Open Source Lab

Write the Docs '15

The day is May 18. The location is the Portland's Crystal Ballroom. The conference is Write the Docs (WtD). Excitement and anticipation fill the air as we collectively munch on breakfast foods and find a seat. The keynote begins and immediately sets the mood: docs are fun, docs are interesting, and here's how you can make your docs awesome.

WtD was quite the experience and it got me excited about documentation, something I admit I never expected to be all that excited about. At times it felt like a support group for non-technical individuals that work with engineers, other times it felt like a storyteller sharing with us their adventure in documenting some massive project, and most importantly it was always engaging and interesting. Some of my most memorable talks were of Twillio's efforts to make their documentation better, GitHub's workflow of writing docs for GitHub with GitHub, and Google's new documentation tool and how it was developed and adopted in a grass roots effort as opposed to a top-down corporate approach. I even gave a Lightning Talk on "How to Write the Best Email You've Never Written... Until Now" which went over very well and seemed to speak to a lot of people.

Inspired by this awesome conference, we have have started a massive overhaul on our documentation including writing official style guides, overhauling the new hire onboarding docs, and updating our wiki. With the new hire documentation we have taken into account lessons learned from the conference, like how we should make docs fun to read in addition to informational; this shift has resulted in our 'Gamified New Hire Docs' rewrite, which essentially gamifies the onboarding process to be more fun. Once one of the new student employees passes a milestone, like submitting their first GitHub Pull Request, they get a reward badge (e.g., a gold star sticker). It might not seem like much, but this is way better than slogging through a daunting pile of docs as one starts a new job.