READMEs

for Open Projects

​

​

Mateusz Kuzak

• Learn how to use a README to communicate your project effectively
• Learn how to write clear description of the project
• Where to find examples
• (assignment) Create or revise your README

What we’ll do

Open Leadership Framework

Open Leaders design and build projects that empower others to collaborate within inclusive communities.

Open Leadership Framework

• Found in the root directory of your repository
• In ALL CAPS, a request for all to “read me!”
• First stop for visitors

​

Could also be: website landing page, session description

What is a README?

• what you're doing, for who, and why
• what makes your project special and exciting
• how to get started
• where to find key resources

​

You can use your Open Canvas to start your README

​

In your README, show:

​

• Welcome message!
• Project description & vision
• Links to:
• How to contribute & get involved
• License
• Code of Conduct, reporting info

​

A closer look at a README:

README example: STEMM Role Models App

• communicate expectations around the readiness
• communicate expectations for and manage contributions to your project
• describe communication channels

What alse?

Badges.

Emojis.

Animated gifs.

HOW can we communicate better?

Image from xkcd, editor at http://splasho.com/upgoer5/

& the Hemingway editor http://www.hemingwayapp.com/

XKCD explained a complicated subject using only the ten hundred words people use the most often

​

Jargon are terms with a specific meaning in a given field, obscure for people outside that field. It can exclude potential contributors.

​

​

​

Let’s try this together.

​

http://splasho.com/upgoer5/

​

Try to explain your project using only the ten hundred most used words

​

Breakout Rooms of 3-4, 10min

Good README examples

• Purple Booth’s README Template
• Standard README - style specification
• PaperBadger - project README
• Thoughtbot’s Blog on How to Write a Good README
• Matias Singer’s curated List of Awesome READMES

What are your README tips?

The Open Life Science program helps early stage researchers and potential academic leaders in becoming Open Science ambassadors.

​

What Open Science dreams will you achieve?