Arguably the single most important piece of documentation for any open source project is the README. A good README not only informs people what the...
For further actions, you may consider blocking this person and/or reporting abuse
Emojis is a matter of taste.
You are missing two important things:
Agreed re:emojis and logo! Have made an edit. Thanks!
The risk of adding a TOC is you push all the important information like the intro/project summary etc further down. I’d only really use one if your README is incredibly long (or I’d move some of that content into another file).
I think if you've got enough info to warrant a TOC, that should follow the initial intro section of the document that describes what the thing is, etc.. AND, that's probably a good time to also think about splitting it into multiple files, ie: instead of a contributors section, a separate contributors.md file, etc.
+1 this is what I did. Once it gets to a certain length ah... you kind of need one up top.
There's also this great tool to generate a README based on your package.json 😄 I use it for all of my projects
That's very specific for Github projects that fit in a fairly narrow window. I know the point of a template is that you use it as a starting point, but for most of the stuff I do, I'd be deleting more than half the template every time.
That's the one linked at the bottom (in the resources) 😉
Aaah sorry I missed it ! Glad you did, it's super useful. Great article James 😄
Thanks for your recommendation, it seems easy and helpful to work 💪
Take a cue from those same old school manuals you reference as to what they include. Who cares about badges and emojis. That's marketing. Put marketing on your site. This is about getting shit done
Most non obvious projects should have a glossary of terms. These are business or non-standard technical terms you need to understand to make sense of the code.
You should also probably have an architectural overview. Charts (plantuml + graphviz ftw there). Enough to convey a high level understanding of how the darn thing is built. There is nowhere better for this.
Justifications for potentially controversial architectural decisions can probably go into issue and or discussions but at least link em!
I've also found a short FAQ section to be a good idea here.
Justifications of potentially controversial decisions as well, as there is simply no better place for them and its important for people to understand.
Thanks for the feedback!
I honestly wouldn't advise including a glossary in a README. Make it a separate file or have it on your documentation site. You can add links to definitions if you really need to.
A simple high-level architecture diagram isn't a bad idea if you want to mess around with Graphviz but anything more complex I'd keep to a separate doc.
If you need an FAQ you should be asking, why aren't these questions answered in my README?
But listen to what you yourself are saying James. You - very correctly in my opinion - start of with the historical perspective, but now are recommending discarding the lessons that were learned in how to compose those very documents. That might make sense, sure, but you'd agree I hope that it would at least need to be justified.
What is the purpose of a README? It should be everything you need to get started in working with the project, right?
And more specifically, the huge benefit over separate docs is that it lives alongside your code and can change in tandem. So if an important architectural concern changes but the related docs do not, you can see and comment on it right in the same pull request! So maybe, once your project stabilizes you can move that stuff to a different linked document but frankly most projects will never get to that level of stable.
As for FAQ... Well if you put it into the README then it *would*be answered there 😉, but I take your point. The reason I end up having it anyways is as a concession to both suboptimal organization (shit, this is important but there's no obvious section for it), and to people who are in a hurry to get stuff done and don't read all the docs.
I'm not saying to discard anything. The early READMEs were absolutely terrible. If there was a lesson to be learned it would be: Do not copy the format of the example README from 1974 😂
I get your point re: it's good to have stuff in one place but if you're using a docs-as-code approach then your docs live alongside the code anyway so all of your docs files will be updated as you update the code.
I guess it's personal preference re: FAQs but for me, they don't belong in a README. Relevant article here: FAQs Are A Code Smell.
I mean the people that created the stuff a lot of our works is based on surely had some aspects of it figured out :)
And yeah I agree an FAQ is absolutely a smell, it's just also often a reasonable concession for when you don't have resources for a more elegant solution.
This is a great (and necessary) introduction to writing helpful READMEs.
The only thing I would add is that I've found GIFs to be even more helpful than screenshots for showing off the functionality of your project.
I have used GIFs in the past (and yes, can be a great way to highlight functionality). You just need to mindful that you’ll need to update them if anything visual changes in your project (like with screenshots).
I use this module github.com/kefranabg/readme-md-gen.... It's easy, straight forward and generates beautiful readme within seconds.
Hey Shad, thanks! Yeah, that’s the last link I put in the resources (see bottom of the page) :)
My bad, missed it. Good article bdw.
Contributors list will be great too,i have created an opensource app which can be used to create markdown ,it allows to reuse commonly used items such as licence or contributors list.
markdownapp.now.sh/
Dude, your profile pic is awesome.
Haha thanks!
I feel like screenshots are a little bit overlooked in repositories. I especially find gif crops that display core features very useful. They are focused and attractive while it takes only a few seconds to grasp context. When applicable screenshots and gifs can provide a nice motivation to drive people into the project.
I've made an open source project to generate README section recommendations based on the most popular repositories for each language on GitHub. Would love yo get your thoughts and contributions: hpbl.github.io/WRITEME
Sure. Is there a repo link so I can submit a pull request or is it private?
Sorry for the delayed response, but yes: github.com/hpbl/writeme
Or you could just follow the standard-readme specs: github.com/RichardLitt/standard-re...
Cool, I didn’t even know this was a thing!
Nice read thanks!
At minimum I try to include these sections:
Any extended advice on what legal to put in a readme? Especially wondering about the situations where you do not want anyone to be using the code. "closed source" if you will.
This is a great question (you also reminded me to add choosealicense.com to the licenses section!) but I don't have an answer for you I'm afraid and I don't want to give you bad advice.
However you may find some useful info in this chapter on Non-Open Source Licenses and The Legal Side of Open Source. Hope that helps!
Wow, great resource nonetheless. You've pointed me towards a "Classic Proprietary License" for projects that contain open source code but is not licensable. Thanks for the great article and reply!
You lost me at Ruby.
You had me at Hello.
Missed opportunity... You had me at 'echo: hello world'
I'm happy to see good tips to add with my already good practices 😜
Thank's for this post.
Very accurate all the info. Maybe I should re-edit all my Readme based in this info. Thanks 👍
What a nice article, check my tool here, i made this github readme generation tool. #justforfun
hmm
Emojis are garbage.
Nice!! Screenshots for me, are one of the most important things.
Thank you sir!
Good stuff
Great article! Thank you. Question: would you insert the link to project's documentation and if so, where would it go?
I created My Github readme
Hi there👋
I am aayushi Sharma. I Love❤️ programming and currently working as Machine learning engineer.
Skills
Things got bugs, gonna smash them one by one