Making Open Work
May 8–9, 2017: Training & Tutorials
May 10–11, 2017: Conference
Austin, TX

The art of documentation and README.md

Ben Hall (Katacoda | Ocelot Uproar)
2:35pm3:15pm Wednesday, May 10, 2017
Open Source: From Consumer to Contributor
Location: Meeting Room 9C
Level: Beginner
Average rating: ***..
(3.43, 7 ratings)

Who is this presentation for?

  • Open source contributors, content editors, and authors

What you'll learn

  • Understand how to build beautiful, useful documentation

Description

The README is key to successful open source projects as a gateway to welcoming new users and potential contributors. It defines the tone of the project, explains how to get started, and most importantly, outlines the project’s aim. While many open source projects have amazing code bases, their README and documentation are not as successful. As a result, these projects are losing influence and opportunities for adoption and feedback.

Ben Hall draws on his experience building an interactive learning platform to demonstrate how small changes to your documentation approach can have an enormous impact on how users get started. You’ll leave with a better understanding of how to build beautiful, useful documentation, backed by examples from some of the best open source projects.

Topics include:

  • How to create engaging documentation
  • How to define technical details in an accessible way
  • How to build documentation that encourages users to get started
  • How to manage documentation and keep it relevant and up to date
Photo of Ben Hall

Ben Hall

Katacoda | Ocelot Uproar

Ben Hall is the founder of Ocelot Uproar, a company focused on building products loved by users. Ben has worked as a systems administrator, tester, and software developer and launched several companies. He still finds the time to publish books and speak at conferences. Ben enjoys looking for the next challenges to solve, usually over an occasional beer. Ben recently launched Katacoda, an online learning environment for developers that helps break down the barriers to learning new technologies such as Docker and containers.