Write the Readable README¶
Description
A README file often makes your software’s first impression. In this talk, you’ll learn to put together a README that makes a great impression, even if you have little time or writing skills.
At the top of your directory tree, your README is your software’s resume: it’s often the first and—if you’re not careful—the last thing anyone sees of your software. But you may not have time to craft a bespoke README. That’s OK! In this talk, you’ll learn:
- why it’s important to have a great README, whether you’re working on a closed- or open-source project
- how to choose what to write first to get the best README in the shortest time
- how to use templates and Mad Libs to avoid common README pitfalls
From your project’s name to what’s in that LICENSE file, you’ ll learn what to write first and what mistakes to avoid, so that your README wows new users, helps colleagues or contributors, and maybe even does your future self a favor.
Like Mike Jang’s Ignite OSCON 2015 talk “Ten Steps to a Better README”1, this talk will recommend style and content, but with a greater focus on the process of writing a README. While inspired by open-source approaches to READMEs—including readings of style guides such as 18F’s “Making READMEs Readable”2 and the READMEs of all projects that have 10,000 or more stars on GitHub— this talk will not be limited to the context of open source.
Whether you're new to the genre or a README connoisseur, you'll learn a process to write a README that works for you and your audience.
- Conference: Write the Docs NA
- Year: 2016
