Table of Contents
Overview
README Files Are Never Perfect
The Primary Purpose of README Files
A Good README Starts With a Proper Struct...
For further actions, you may consider blocking this person and/or reporting abuse
I'm so going to update the READMEs for the SDK I maintain to follow this format!!
I would suggest a contributors section. It's good to call them out when you're trying to build out community awareness
Go for it sir! Use it and modify it according to your requirements. I’m glad this helped you!
A contributors section sounds like a brilliant idea. Thanks for the suggestion!
Already have Copilot running 😝
Awesome!!
This is one of those posts where I don’t have to mentally fill in gaps—you actually covered the full surface area really well. Honestly, this is how all README structures should look across the board.
I like that you call out the image at the top. READMEs just land better when there’s something visual pulling people in right away, and a lot of folks still skip that. Same with the badges—you’ve got them in there, but they’re worth highlighting. I’ll take any excuse to drop in Shields.io badges to break up text and give quick signal at a glance.
Also worth adding Mermaid to your diagrams list. GitHub supports it natively, and keeping diagrams in markdown makes updates way less painful than jumping back into something like Lucid every time you need to tweak it.
Fair warning: I’m probably going to steal this and turn it into an AI skill. It’s too clean not to! 😄
Well put together @georgekobaidze.
@anchildress1 about your point with shields.io, my big problem with README badges has always been that shields.io badges look like they're from 2014. I built shieldcn to fix that. It renders badges as actual shadcn/ui buttons via Satori, so they match the design language most modern projects are already using. Same URL patterns, drop-in replacement, just way better looking IMO.
Totally agree on the visual-first header point. A good logo + branded badges at the top immediately signals "someone actually cares about this project." People decide whether to keep reading in the first two seconds.
Great insights! Thank you for the feedback!
Mermaid for the win!
Thanks for the great feedback! Feel free to feed this to AI, I’m happy to contribute to its learning. 😄
And thanks for the Mermaid suggestion, I’ll definitely try it out!
Finally, a README guide that treats documentation with the same engineering rigor as the code itself! The 'future you' argument is the most honest motivation for writing good docs. I’m definitely grabbing that ready-to-use template for my next project. To anyone reading: don't skip the Architecture diagram—visual signal beats text walls every time. 5 stars!
I'm glad you've found it helpful. Thanks!
Thank you for this guide. Reading your article made me realize how infant my default README.md looks like when compared to what you write. I'll try to add sections in my future projects when I get the right opportunity to do so.
Thanks for the feedback. As I mentioned in the article, README files are never perfect. My README files aren’t perfect either, we should constantly evolve and polish them.
Good luck!
This is a strong, practical guide.
What I like most:
One push:
Overall, this is the kind of guide that can genuinely improve open-source quality if people follow it.
Thank you for the great feedback!
Great writeup. I would add one little thing to the getting started that seems trivial but not everyone on GitHub knows how to get started...really started.
Include the basic commands on cloning the repo cd into and then 'npm install' or whatever is needed. It's two extra lines and could save some future new coder a few minutes of headache.
Starting your install instructions at 'npm install' is somewhat like telling a new driver to put the car in gear before telling them how to start it.
Agreed! Though I usually write that sort of stuff in the "Getting Started" section (or it can be named "Setup", based on preference)
Great breakdown - practical, clear, and genuinely useful. The emphasis on structure and readability makes this one of the better README guides I’ve seen. Definitely borrowing some of these ideas for my own projects.
Thanks for such a great feedback!
You're welcome!
15 sections is ambitious. best small-project READMEs I've used top out at 4-5 - setup and core pitch. anything more starts feeling like documentation theater for a tool with 2 contributors
Good point. And you’re right, that’s why I mentioned that in specific cases you might not need all of these sections. But usually they come in handy more often than not.
I’ve even seen README files that add more sections based on the requirements and specifics.
fair enough - project maturity and audience changes the calculus a lot. i trim harder on internal tools than anything public-facing
Right, internal tools usually don’t need sections like “How to Contribute”.
exactly - the whole contribution guide thing is mostly for external audiences. internal tools get away with 3 lines of setup and a Slack message.
Well, for me they usually end up more than a few lines but yeah, they're definitely shorter.
This is a really solid breakdown.
I’ve started thinking of the README as the first user experience of the project, not just documentation.
If setup or intent isn’t clear there, most people won’t go further.
Having a structure like this makes a big difference, especially for real-world projects.
It does make a huge difference. Thanks for the comment!
Woooow, what an awesome read!!! 😍😍😍 As a Technical Writer, I fully approve! Happy to see engineers who care about documentation and understand its importance; it really lifts the spirit.
As a few other commenters have noted, I also think that such a long README can be a bit of an overkill. A good option could be moving some of these sections to the
docsfolder with more detailed documentation. The README could then contain a reference to the docs. CONTRIBUTING.md is very often also a separate document.Thanks, I appreciate the great feedback! And yes, a README fine can be too long if it contains these sections, but only if these sections contain too much unnecessary information. You always need to make sure to write just enough in your README. And “just enough” is an important keyword here.
Great breakdown! I especially appreciate the "Troubleshooting" section callout—it's often overlooked but saves so much time for new users.
One thing I'd add: for AI agent projects, a "Memory & State" section can be crucial. Users often ask "does this remember context across sessions?" Having that explicitly documented (with examples of what persists vs. what doesn't) prevents a lot of confusion.
Also, the "Roadmap" section is gold for open-source projects—it sets expectations and invites contributions in the right direction.
Thanks! Interesting suggestion, though many projects don’t really utilize memory and state, so I decided not to include it here.
As for the roadmap, that’s pretty much the same as “What’s Next”.
Good list. I just open sourced a 65,000 line Rust
project this week and the README was one of the
hardest parts to get right.
The one thing I'd add is that for technical projects,
the Getting Started section needs to actually work.
Not "should work" or "works on my machine" but
genuinely tested step by step. I went through every
command in my tutorials on a clean devnet and found
bugs that would have made the whole thing useless for
anyone trying it for the first time.
The Architecture section is underrated too. I wrote a
full crate-by-crate walkthrough with Mermaid diagrams
for the consensus flow and transaction lifecycle. It
took a while but it's the one doc that gets the most
use because it answers the "where do I even start
reading this codebase" question.
One section I'd add to your list is a Security section
with a vulnerability reporting process. Especially for
open source projects. Even a simple SECURITY.md that
says "email us here" is better than nothing.
Absolutely, the “getting started” section should be well tested and working. As for the “security” it’s definitely necessary in most cases, the article mentions it, but having a separate Markdown file for just security purposes is sometimes a better practice in specific scenarios.
Agreed on the separate SECURITY.md. We did that too.
The README just mentions that it exists and links to
it. Keeps the README focused on getting started and
the security details in their own file where they
belong.
Sure. That’s just another way of doing it. That one’s especially helpful if you need to describe and document security in a more detailed way, or if it’s way too complex for your README file.
Posts like these are almost nonexistent but they are so incredibly important! Thank you!
Appreciate that a lot! I always try to avoid getting pulled into "what’s trending" or "what grabs attention." I'd rather have fewer views and write about what I enjoy.
And it works beautifully!
Thank you ! I get that 100%
This is one of the posts that turns into a reference title in my repo. Very nice!
The image at the top of the readme is a chef's kiss! READMEs should be treated like any other post in the sense of imagery captures attention and communicates the tone of the post/article.
5 stars.
Thank you so much!!
Thanks for the article. I found myself among those whose want to place everything inside it instead of splitting it into a separated docs folder. I learn it recently while working.
Thanks for the breakdown into section and the mention to place only useful information not all your though in it 😅.
Thank you. Appreciate your comment!
Really good base. I love Skillware for it is super clean and starts high level, but then expands the more you understand and dive deeper. Super long readme feel like info bombs at start and can have the opposite effects of what you have. I would generally try to use githubs native license, contributing, security etc. which appear as seperate tabs, instead of hard coding into the readme. You can maybe have hyperlinks to them, but not dedicated sections. Overall very good for anyone who is just starting with their first gh projects <3
Interesting points, yeah there are so many options for every scenario, which is great!
This is actually a good reminder.
I’ve skipped writing proper READMEs a few times thinking I’ll “do it later” and then come back completely lost myself.
The “future you” point is real.
Also like how you kept it practical instead of overcomplicating it. Easy to follow.
Thank you. And yes, we should always make life easier for future us.
thanks for this guide! you explained everything really well, im gonna update my READMEs now!
Thanks for the great feedback! I’m glad it helped you! Feel free to use it.
Thank you this is really valuable information. Every repo should have table of contents.
I have been so confused about how to write the README file I will start using this template for my projects.
I'm glad to hear it helped you! Feel free to use it and make it better.
Great insights here. Thanks for the template and the read!
Thank you!
I was writing a README when dev.to suggested this. It's really good!
What a perfect timing! Love that!😄
Good reminder well-structured READMEs improve adoption, clarity, and collaboration. Most projects fail not from bad code, but from poor documentation.
"Most projects fail not from bad code, but from poor documentation." <-- that line really should've been in the article. It's just spot on. Poor documentation frustrates everyone and frustrated developers rarely build successful projects.
This is a thing of beauty 🥹
Oh, you just made my day, thank you!! 😄
Thank you
You’re welcome!
Great checklist! I’d also add a ‘Common Issues / Troubleshooting’ section — saves a lot of duplicate issues on GitHub. Thanks for sharing this.
That’s a great point! Thanks for the suggestion!
Thanks
🙏
დავანოუთებ :დ
მადლობა!
Thanks for the article. It's a very good reminder not to skip on it, not to skip on the proper documentation. I have a tendency to do just that. Ha ha.
Thanks! It's actually a good reminder for myself too, because I've had my fair share of moments when I was way too lazy to write a proper README file, which was a mistake.
This is an amazing read which covers virtually everything. I don't use visuals in my README and i would have to implement that.
I’m so glad it inspired you to make your docs better. Thank you!
nice!