Telling a Great Story on GitHub


As a former journalist, I tend to think in terms of storytelling. As an open source evangelist, I invite you to do the same. What you share on GitHub tells a story about you, your development practices, and your openness to others in the open source community. If you're motivated to gain users, contributors, and positive feedback about your projects, then building a compelling, coherent narrative is essential.

In this presentation, I'll share insights gained from curating Zalando's GitHub repository so we can tell a better story. I'll describe how we've used GitHub and other tools to create guidelines and processes that bring sanity to our storytelling. And I'll talk about how focusing on higher-quality docs has helped us to instill a stronger product mindset in our development teams. Writing a README, for example, offers an opportunity to tell the world why a project exists, how it works (and why), what makes it unique, and how it might evolve over time. I'll discuss how this process not only empowers developers, but also those of us who are technical writers and storytellers—offering several real-life examples to (hopefully) inspire you.

From 400+ projects of widely differing quality, reliability and maintenance levels, we've winnowed our OSS offerings at Zalando to make our highest-quality work more discoverable and user-friendly. If your organization is facing GitHub-bloat challenges, looking for ways to manage your repos more effectively, or wondering how better docs can help your OSS efforts succeed, you might find some help here.

  • Conference: Write the Docs EU
  • Year: 2017

About the speaker

Lauri Apple