Foundations Course: How to write a README file

[ghost]

Complete the following REQUIRED checkboxes:

• I have thoroughly read and understand The Odin Project Contributing Guide
• The title of this issue follows the location for request: brief description of request format, e.g. NodeJS course: Add lessons on XYZ

The following checkbox is OPTIONAL:

• I would like to be assigned this issue to work on it

---

1. Description of the Feature Request:
In the html assignment of odin-recipes it tells you to write out a README file to talk about what skills you used to complete and what you learned. I thought it may be a good idea to add a section around the Git Basics to how to properly write a README file.

2. Acceptance Criteria:
[ ] Add section in foundations to create README file
[ ] How to use markdown
[ ] What information to include

3. Additional Information:
n/a

[ChargrilledChook]

I don't have much free time and I'm currently working on a different lesson, but if there's no urgency on this I would be happy to pick it up afterwards. It's something that's in my wheelhouse.

Alternatively happy to help out if someone else wants to work on it.

[DaeguDude]

@ChargrilledChook Would it be okay for me to work on this? I am also not sure if I could finish it in short amount of time, but happy to work on this.

[ChargrilledChook]

@DaeguDude Fine by me. I'm happy to collaborate / assist if you would like*. Feel free to DM me about it 👍

*(After we hear back from the maintainers)

[01zulfi]

@DaeguDude @ChargrilledChook Before we start any work on this, I believe discussion is due.

I like the idea in general, but the question is how do we want to tackle this. One question I'd like to raise is do we need a dedicated lesson on writing READMEs. What are the pros of doing so over linking to an external guide on writing READMEs in the Recipes project. On contrary, there are so many guides out there that it's just easier for us to write our own instead of deciding on which guide to choose.

If we do decide for a lesson, where would we place it. Personally, I believe placing it around the Git Basics lesson would be a little too early because we'll be exposing users to information which they won't likely need until the Recipes Project. So right before the Recipes project sounds ideal, though I'm still on the fence about it.

Thoughts are welcome!

[DaeguDude]

@01zulfi @ChargrilledChook

One question I'd like to raise is do we need a dedicated lesson on writing READMEs.

Now you are raising a question, to be honest I couldn't really think of the pros of writing a new lesson over linking to an external resource for minutes. However one benefit I can think of is, with a new lesson it could deliver more importance to the learners that it's important to know how to write good READMEs over just linking to an external resource.

If we do decide for a lesson, where would we place it. Personally, I believe placing it around the Git Basics lesson would be a little too early because we'll be exposing users to information which they won't likely need until the Recipes Project. So right before the Recipes project sounds ideal, though I'm still on the fence about it.

I also agree that placing it around the Git basics lesson would be a little bit early. Since they haven't set up any project yet but learning how to write good READMEs could seem a bit out of order. But I also think since they learn how to make a README file and push that to github repository in Git basics lesson, it wouldn't hurt too much either putting the lesson right after it since they'll be knowing how to write good READMEs going forward in all upcoming projects.

But yes, if it is put right before Recipes project, I think learners will be more aware of it than having it after git basics lesson.

[01zulfi]

@DaeguDude Apologies for the late reply.

If we do decide to go for a lesson, can you share a rough lesson outline on what sections the lesson will have. This is just so we can narrow down the specifics.

Once we have a rough outline, we can reassess on how to proceed further and decide if a lesson is worth it or not.

[ArjunSaili1]

Hey @01zulfi & @DaeguDude, just recommended the same idea in the suggestions channel on Discord. I made a basic list of advice I think should be included for this lesson (if it gets made):

• Use Media in READMEs (Photos, Videos, Gifs, etc.)
• Explain your development process
• Explain your motivation behind the project
• List out the technologies you used
• Provide information on how to run the project
• (If applicable) Provide information on how to contribute towards the project
• (if applicable) License information
• (if applicable) Credit any resources being used (images, starter code, etc.)

As for if this information should just be included as a resource or have a dedicated lesson, I'd argue a lesson would better signify the importance of READMEs. There are definitely a lot of guides out there for making READMEs so I understand why it might seem unnecessary for TOP to have its own. However, I think READMEs are critical for not only thoroughly explaining a project but for also providing an opportunity for a learner to reflect on the information they learned. By making lesson, we're basically signalling the importance of this information and make sure learners are understanding how to make a README before moving on to the progressively more valuable projects.

i'd love to hear what you guys think as well!

[KevinMulhern]

Converting this to a discussion until we have something decided on and actionable.

[CBID2]

Loving the discussion here. @KevinMulhern, I think this could be Markdown course and a ReadMe file could be the assignment since the language is used to create this document. I’m also eager to work on this.

[aScHEABL]

I don't really think writing README.md worth a dedicated lesson, the idea of it is silly.

[CBID2]

I don't really think writing README.md worth a dedicated lesson, the idea of it is silly.

How is it silly?

[stephengroe]

Hey all, reviving this thread because I think it’d help a lot of students. 🙂

A good README is one of the most important parts of a beginner’s portfolio—few hiring managers will read a whole codebase, but almost everyone will glance at the README.

Despite that, many (if not most) of the TOP student projects I see have empty or one-line README files. Sharing some best practices could help their portfolios stand out in today's tough job market.

If we want to add this, I think these are the best sections to consider:

1. Foundations, Recipes project. Currently, there are two lines about a README. We could expand this to a subheading, similar to the “Tips on when to commit” section.
2. Foundations, new lesson before Recipes project. This would be a bit more comprehensive and might look similar to the lesson on commit messages, which currently precedes the recipes project.
3. Getting Hired, Building Your Personal Website project. This is probably less ideal because it’s so late in the curriculum, but doable. This project briefly covers READMEs and we could add more detail.

I’m happy to write this content or find the resources to help make it happen!

[mathdebate09]

Moreover, learning to write good documentation is really good for beginners, sections on how to replicate the project locally, how the project works, technologies used, etc. also help build understanding about one's own project and explain it verbally to others.

[Asmatzaile]

Hi!
I understand that the general consensus is that the lessons should give more importance to making a good README file, but there is some disagreement over whether it should be a dedicated lesson or simply to add explanatory text in key places.
I feel that putting the second idea in action is a step forward that everyone could agree on; and the discussion about whether to make it a full lesson could be carried on later.
So I propose, for now, removing the fourth step on Setting up your project's GitHub repository and adding a new subheading before Tips on when to commit, named Writing a good README file or similar. There we could offer a 'structure template' for learners to follow. I think that the most important aspects are:

• Describe what the project is
• Provide information on how to run the project
• List out the technologies it uses
• Explain your development process
• Credit any resources being used (images, starter code, etc.)
• (if applicable) License information

We could explain that although the standard for GitHub READMEs is to use markdown, one can use HTML to mark the structure of the document, and that many tags, including , work in .md files. We could also put a link to somewhere with more info about Markdown.

Also, I think that in the "Computer Basics" lesson, right after "Open source vs closed source software", we could add a reading about types of open source licenses, as choosealicense.com, so the learner can refer to that when deciding about the license information of the README.

For the structure template, I took into account all suggestions made by @ArjunSaili1, but there's one that is missing, namely:

Provide information on how to contribute towards the project

I do think that giving info about this would be overwhelming at this stage, as learners will have very little experience using Git and GitHub.

I could work on this if it's agreed upon.

[aScHEABL]

This post is from almost 3 years ago...
Perhaps open a new thread yourself?

[Asmatzaile]

Why though? The topic is still relevant and unresolved; opening a new thread would cause duplication