Documentation...What do people NEED to know!?

The web-dev journey with ruby on rails this past year has been quite the rollercoaster ride. I have learned A TON of things about how to organize data and build effective databases. BUT one thing that I just totally skipped over while I was wondering around ruby-land was WHAT THE HECK do people need to know when I am writing documentation?! What qualifies for good documentation and what is the easiest, most concise way to write documentation?

As I have moved forward with my learning I have learned a ton. Reviewing my passed projects is what inspired me to really hunker down and focus on answering the question about what good documentation looks like. Because the bottomline is that proper documentation is just as important as the code and tests themselves.

Now I have read loads of documentation over the last year. Trying to learn as much as I can about ruby and rails and implement what I have learned in effective ways. And some of the documentation I read was great while others left me with more questions than I had answers.

While cleaning out my GitHub of the old projects and refactoring my favorite ones. This process has been really great because not only have I revisited just how much I have grown over the passed year but it is challenging to try and debug old code and refactor it into more efficient bits of code. The bullet points below is part of what I am learning along the way and some of the questions I am trying to remember to ask myself as I am refactoring these repo's:

1. What does a none-ruby dev need to know in order to run this project?

   • There are tons of new developers heading into the world of code everyday. Some of the things that I wished I saw more of were repos that assumed I knew nothing about the program that they were writing.

2. What does this project do?

   • Whether it is a card game that is played in the terminal, a full-stack app, or just an api. The other person on the other end of the readme should be able to look over the readme and understand what it is that they can do with the program they are looking at.

3. What are the goals of this project?

   • This may not be super important but I have always liked reading what the initial goals of the project were as well as what the developer is looking to work on in the future. It is super cool to keep track of the growth of your apps.

4. In my Table of Contents, what are important headers that people might want quick links too? (below are the ones that I lean toward)

   • Project Description
   • Run and install: What gems are in this app? how do I install them, or what links to documentation does the user need to be able to install them properly.
   • How does the user use the program on the localhost?
   • Endpoints: Explicitly what are the routes, and what should I expect to return
   • Architecture and Design: What do the tables look like and how are they related (connected)?
   • Feedback: Not necessarily a must have but I have loved the idea of people being about to create pull requests to make changes/share ideas to a project, so I am working to add this to all of my projects.
   • Credits: Don't forget to give you and any collaborators credit for the work that they did on this project! I like to connect my LinkedIn and GitHub Profiles so that people can reach me if they have questions

This is what I have found so far to be helpful in guiding to creating the most readable and readme. If you have any suggestions about things you have found helpful when creating documentation, let me know in the comments!