README structure: single file or one per folder?

[nataliapaulino]

Body

Hi everyone!

I’m organizing a repository to document my personal programming studies and have been trying to keep things clear and well-structured.
I currently have a main README.md at the root of the repo, and I also created another README inside the SQL folder to provide more context for that specific section.

My question is: do you think it’s a good practice to include separate READMEs in each folder (like per language), or use a single README with a well-organized table of contents to make navigation easier?
I’m still adding content and plan to include C# and other languages in the future.

I’d appreciate it if you could take a moment to review the SQL folder README here and the main README here, and share your opinion.

I’d love to hear how others approach this kind of organization.

Guidelines

• I have read and understood this category's guidelines before making this post.

[r2hu1]

Hey! I think having a main README plus separate README's in each language folder is a great idea. It keeps things organized and focused, especially as you add more languages.

Just make sure your main README has a clear table of contents linking to those sub-READMEs for easy navigation.
Your SQL README looks good, consistent style across folders will help as you grow.

Overall, this approach strikes a nice balance between overview and detail!

[Sriharan-S]

Hey there! That's a really great question, and honestly, your instinct to create a separate README for your SQL folder is spot on. It's exactly how many experienced developers keep their projects clean and easy to navigate.

• Your main README.md at the root is like the lobby of a building. It greets visitors, tells them what the building is for, and has a directory (your Table of Contents) pointing them to the right floor (or folder).

• Each README.md inside a folder (like /SQL/) is the welcome mat for that specific floor. It gives all the juicy details about what's happening in that one area, so people don't get lost.

Going with this approach is a fantastic idea, especially since you plan to add C# and more languages later. It keeps things from getting cluttered and makes it super easy for both you and others to find what they're looking for.

Honestly, it shows you're thinking ahead about structure, which is a huge plus. Keep up the great work!

Mark it as an answer if you find it helpful. Thanks!

[vizzv]

Hey !

This structure makes sense and seems well thought out. Having a main README.md for general context and navigation, along with subfolder-level READMEs for each language or topic (like SQL, C#, etc.), is a scalable and clear approach—especially as the repository grows.

It can also be useful to create README files for specific programming concepts such as functions, classes, inheritance, OOP principles, etc. These could contain definitions, differences (e.g., between procedures and functions), examples, and even common questions, making it easier to revisit or share specific topics.

For managing such structured notes, tools like Obsidian.md can be helpful. It works well with markdown, supports internal linking, and integrates easily with Git for version control. I am also using Obsidian for my japanese language learning and use git for syncing, You may check that repository here. I am also managing it in md files. You may look at my japanese learning repo and my get inspiration or idea.

Mark it as an answer if you find it helpful. Thanks!

[mecodeatlas]

Welcome to the GitHub Community, @nataliapaulino, we're happy you're here! You are more likely to get a useful response if you are posting your questions in the applicable category and are explicit about what your project entails--giving a few more details might help someone give you a nudge in the right direction. I've gone ahead and moved it for you. Good luck!

[github-actions[bot]]

🕒 Discussion Activity Reminder 🕒

This Discussion has been labeled as dormant by an automated system for having no activity in the last 60 days. Please consider one the following actions:

1️⃣ Close as Out of Date: If the topic is no longer relevant, close the Discussion as out of date at the bottom of the page.

2️⃣ Provide More Information: Share additional details or context — or let the community know if you've found a solution on your own.

3️⃣ Mark a Reply as Answer: If your question has been answered by a reply, mark the most helpful reply as the solution.

Note: This dormant notification will only apply to Discussions with the Question label. To learn more, see our recent announcement.

Thank you for helping bring this Discussion to a resolution! 💬