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.
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.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
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.