Writing Good Documentation

Learning Goals

Understand the reasons for writing a solid README
Determine what to include in a README
Use your README as a tool for your eventual job search

Vocab

Markdown: a lightweight markup language for creating formatted text using a plain-text editor; we use this for READMEs
README: a form of documentation for a project directory

Introduction

You have all seen READMEs before. Take for example this assessment. Github displays the README file for the viewer since it holds the main information for the project.

The Why

We often think of READMEs as an afterthought in our projects, but they are SO important! Here are some ways that READMEs matter to you and your eventual job hunt:

To an employer, your README is often the first impression of the work you’ve done
Sometimes employers only scan the README and don’t even open the project
Your README is how someone knows how to access your project (It should be written in a way that non-technical people can understand)
The README documents your experience and process to an employer (which is way more important than the project itself!)
Looking back at past READMEs is a great way to remind yourself of all you’ve done and prepare for interviews
Taken cumulatively, your READMEs document your technical and professional growth

Judging READMEs

In your breakout rooms, look through the READMEs below. We’re going to go for first impressions here, so spend about 1 minute per README. Make some observations about the READMEs and add some stickies to this Jamboard

README Links:

Some potential takeaways!

Too many images can make it too chaotic
When information isn’t shared in a logical order, it’s hard to follow
Deploy links and install instructions should be one of the first things you see

The What

So what should we include in a README? Well, it’s not a one-size-fits-all thing. Depending on your project, what you’re the most proud of, etc., you may want to highlight different things in your README. Here are some things we recommend including:

Set Up Instructions
Deploy Link (if applicable)
Abstract/Elevator Pitch (what problem is app trying to solve?)
Contributors (including who owned what pieces?)
Links to Wireframe/Planning docs (if applicable)
Tech Stack (including testing + accessibility)
Context (time allotted, # of people, mod, learning goals)
Wins/Challenges (personal or team)
Future Additions (these should be entered as Issues and on your Project Board as well)
ONE gif (show the highest impact feature of your app)
You can add comments in your README for things you want to document but don’t want shown (just remember these are still viewable to everyone in the raw file)

Obviously including all of this would be a bit much. Think about - What do you want someone to know about this project AND what do you want to remember about this project?

The How

Markdown, the language of READMEs, can be tricky at first. Here are some guides to get you started. And as always, Google is your friend!

Updating a README

Open up the README from your Mod 3 Message Logger project and make some updates to it based on what you've learned in this lesson. Be prepared to share the new version of your README with a small group.