| Time | Activity |
|---|---|
| 5 MIN | 🏆 Learning Objectives |
| 30 MIN | 📚 Student-to-Student Review |
| 10 MIN | 🗣️ Introducing Some High Quality README Files |
| 30 MIN | 🔥 README please! |
| 10 MIN | 🛏️ BREAK |
| - MIN | 🗣️ Share some tools |
| 60 MIN | 🚜 Coding Activity |
| - MIN | 💪 Q&A + Wrap Up |
By the end of this class, you should be able to...
- Provide feedback to a project owner in an efficient manner
- Understand what makes an awesome README
- Create and update great README files which guide users to success
- Facelift an existing README file from one of your portfolio projects
Why should we learn this?
- Constructive feedback is an artform and practiced skill! The more you use it, the more you'll recieve in return. More feedback = better products (usually)...
- A great README helps ensure adoption. Nobody will use a product if they don't know how to use it.
Your trusted peers working in the same space as you should always be your go-to for feedback on your project--especially during the early stages of development!
This review activity will emulate the process of asking for feedback and discovering unseen oppurtunities with your work.
Break out into pairs and do the following (each student will get 15 minutes to share):
- The student getting feedback should share their project links and refactoring plan
- The student providing feedback should open the project on their computer and share their screen
While we're providing feedback, we should be thinking if of it as an organic discussion with ample time for both sides to talk.
For the student providing feedback, here are some questions and ideas to use as a starting point in your review:
- What elements are confusing or require clarification? For example, where is the entry point?
- What conventions do you see being employed, what areas could use some?
- Can you see any functions or objects that could be streamlined? Vice versa, do you see any spaces an object can be used in?
- Any compiler warnings or strange behaviors?
- Does the application make sense on a wholistic level (aka does it server a purpose, do all the features align, etc.)?
Let's identify some elements of a great README file as a class.
The instructor will look bring up some of their own README files, some README files they've liked in the past, or talk about what they see in the following examples:
- Node-chat – a simple description with great screenshots and descriptions
- WebApp - great landing page and usage of images, with solid API documentation
- Pomolectron - cool logo and simple usage/installation instructions
Form groups to identify some great README files and build a template for what you want to use as a standard in your own README files moving forward.
Groups should open up the Awesome README repo and look at examples from the list.
Find an example that does a great job of the following:
| README Element | Examples |
|---|---|
| Titles and Internal Titles |
|
| Introduction and Purpose of the Product |
|
| Features and/or Feature Scope |
|
| Table of Contents |
|
| Technologies, Supported Dependency Versions, and Badges |
|
| How To Install/Config/Launch |
|
| Table of Contents |
|
| Illustrations or Logos |
|
| Gifs or Other Images |
|
| Link to Demo or Other Examples of Use |
|
| Sources |
Anybody have some cool image editing software or tools they'd like to share?
Here's some solid freeware to consider when hacking together a README:
- Pixlr = it's like a free photoshop in your web browser
- Giphy = a well known .gif making and hosting service
- Vectr = a free online vector based graphics program for making quick and dirty logos
Use the best examples from the group activity to get inspired and update your README of the portfolio project selected from the first class sessions "Portfolio Project Audit" assignment.
Once you have your README looking top notch, take a moment to reflect on the changes you made. Can you document this process somewhere for future README constructions? How can this be turned into a work flow or procedure you do for you all your big projects?
Finally, take the time to ensure that your project utilizes at least 5 of the following conventions:
- Variables are clear intuitive names
- Casing follows conventions
- Lines are short and terse
- Indentation/Formatting is consistent
- Comments are clear on complex code
- Modules are flexible and logical
- Test Cases file with proper TDD/BDD conventions
Let's see those beautiful README files! Anybody willing to share the fruits of their labor?