README_spike.md

README Spike

1. What is a README?

(high level overview)

A helpful reference document attached to your project that offers:

- overview of the project 
- explanation of file structure
- instructions for cloning/forking and running the project locally 
- names of contributors often with links to their Github
- link to project in production if applicable 
- bugs that are known to the developers
- helpful troubleshooting tips 

• commonly associated with open-source software

• the main type of documenation you will write at Turing

• a place to demonstrate developer empathy!

One of my favorite, most useful README files: Faker

A helpful, funny, delightful README: Slackbot Tutorial

More great README examples: Awesome README

2. What is Markdown and how to use it

(references and tips)

Cheatsheet

• The trickiest part is adding images

  • to use a local file, you can drop it in the comments and then use the generated link in your markdown!
  • for a [Rails] project, put it in the public folder and then use public/image_name.jpeg in README markdown

• Bonus If you can add images, you can also add GIFs!🤯

  

• If you end up creating a large document, a table of contents is always nice

  • Example

  • use the same mardown you would for a link, but instead of a link use # followed by the section name. Then put target beside the section header.

  • example:

    • [1. Introduction](#introduction)
    • <a name="introduction"></a>

  • Think of this as internal linking

• Find yourself wondering "how did they do that in Markdown?" Just checkout the raw file!

• Last thought on Markdown: Use it in cards on your Github project board for extra slick formatting!

3. How to create a README for your github profile

(The good stuff)

What is the function of this?

• As job seekers, this gives us an opportunity to introduce ourselves to prospective employers and direct them to what we want them to see, for instance code reviews, pull requests, commit messages, and repos.

• Include links to social media, LinkedIn, Youtube demos, etc. Example

• It's a place to show some personality! Example

Tutorial from Monica Powell

• This tutorial includes a bunch of cool examples to inspire you!

• Once again, if you want to know "how did they do that?" just checkout the raw file!

Github employees seem to have interesting ideas for how to use this feature: Example

Step-by-step how to:

1. Create a repo with your username

2. Create a README in that repo

3. Write some stuff and then commit changes

4. Boom!

If you are interested in tracking profile views, this tutorial explains how to embed an image to count and display profile views.

4. How to write a great README for your projects

(The really good stuff)

Why should you do this?

1. Developer empathy

• this includes empathy for yourself! weeks or months from now you may forget some of these details of this project and future self will thank past self for taking the time to write it all down while it was fresh.

2. Your project will stand out!

• Many of the projects we make at Turing are not unique. This is your chance to highlight what you did that was special.

  • Is there a production link?
  • How did you handle technical debt?
  • What was your tech stack?
  • Did you use any cool gems or libraries?
  • What was your test coverage?
  • How would you refactor or expand in future iterations?
  • FLEX: Example of flexing refactor and showing new skills

• Also the mere presence of a polished README will make your project stand out.

3. Demonstrate to prospective employers that you are job ready

• Link to project in production
• Demonstrate test coverage
• Display agile process
  • take the time to write reflectively about what you would have done differently, what technical debt you created and/or what you like to do in future iterations
• Talk about how you collaborated with your team and project managers (instructors)
  • Link to project management and discuss how you used it effectively
  • Give overview of technologies that facilitated communication
    • This can include some critical reflection on how the technology was inadequate and what would have been more helpful in the future

What can you include?

- Project description
- Database Schema [dbdiagram.io](https://dbdiagram.io/home) makes this super easy 
- Contributors with links to their github
  - Describe how you collaborated (PRs, Code Reviews, etc.) 
- Tech Stack (with relevant links) 
- Implementation Instructions 
- Test coverage and instructions for how to run tests 
- Code snippets 
- API endpoints (either created or utilized)
  - example request and response
  - use code snippets or screen shots from terminal or Postman
  - the more API documentation you read, the more you'll know what is helpful!
- Reflection 
  - Successes 
  - Challenges 
- Future Iterations 
- Design Strategy 
- Optimization 
- Project management

More resources:

Presentation Notes

Write the Docs Community

How to write a kickass README