I would also say in the "what is it" part that projects intended for a broad audience should avoid jargon as much as possible. It's frustrating in my experience to have to google several acronyms before I can even tell what the purpose is. (Security projects/programs are notorious for using way too many acronyms for example)
My rule for writing documentation is as follows: first use of a commonly abbreviated term is written in its complete form, with the acronym or short form in parentheses. Then, the rest of the text in that same page can freely use the shorter form as needed.
So "the File Transfer Protocol (FTP) is bla bla... When using FTP, remember to bla bla..."
I think that's the most structured and correct way to introduce an acronym. Another style is to use "short form (long)" but "long form (short)" feels better to me (although I'm not a native speaker so maybe I got it the other way around!).
It would be nice if the app would allow us to save templates (no need to get fancy just via URL params e.g. for the above it would be something like:`?sections=title&Desc,installation,runLocally,Support,Authors,Ack,usageExamples`
That way we could just generate a 'template' that we can share/save etc
I would call it "an easy way to create a very full featured README" because it's not easier than just loading a snippet or template in ones text editor, but it does offer a very easy way to add specific sections and to customize them.
The "Get Started" button goes right to the editor with three panes: list of sections to include, plain text editor for the current section, and rendered preview. There's no sign up, and the results can be downloaded directly. Very nicely done little app.
I felt the default sections were missing something, so I easily created this:
## Dad Jokes
- Q: did you hear about the two antennae who met on a roof top and fell in love?
- A: well the wedding was okay, but the reception was Great!
What does this tool give you that a regular markdown editor (like the one available at GitHub ) doesn't? Suggested sections? It seems like just another markdown editor to me but I'm probably missing something.
I glanced and I don’t see anything you don’t. Just give me a list of suggested headings and a plaintext editor. All this does (as far as I can tell) is save you from typing the headings yourself. If using markdown, there’s some additional formatting being applied (which I’m not saying isn’t handy), but really, who needs a website to do this?
It's a markdown editor with templates for common Github README pages. That's useful, even if it isn't (so far) technically all that complicated. I poked around it and feel like I would probably end up with a better README using this than if I just threw it together in Emacs. That's interesting.
I don't understand either why you would need a whole web site to remember "Readme, Usage, Setup, Credits, Release notes, etc."
Feel free to write whatever you want. People forgot (or they are too young) that old READ.ME files were literally free form (with ASCII logos and stuff) and didn't bother with such details.
I used to try do hard with READMEs. Nowadays on my internal tooling I put a few helpful commands, screenshots (my goodness the amount of programs on GitHub without a screenshot of what it does or how it looks), and some info on file formats. I've found that gets me most of the way with minimal effort, vs a very well formatted, nicely laid out, etc etc which takes so long I run out of time for the crucial stuff. Maybe it'd be different if not every user was a 3 minute walk from me.
AI Generated image serving as a Logo/social preview/etc
Badges(I really want 88x31 to be a thing again!)
Quote(I usually try to find a quote for every heading, the way books used to for chapters)
Elevator pitch, 1 or two paragraphs should be enough to know if the project is relevant to you.
Heading (Add an emoji to your headings to make it feel like a proper git project)
Install instructions. If this takes more than a paragraph I assume your project is tinkerers-only stuff that's going to need maintenance, so I like to show off how few steps are needed.
The quotes are mostly flavor/Easter eggs, but they do have a function breaking up the wall of text feeling, as a more fun alternative to whitespace that also acts as a visual marker with a recognizable texture.
OT: I'm looking forward to an AI tool that can look at an entire project and produce documentation for it. Then look at PRs, stories, and other project documents and understand how the project is changing and keep the documentation up to date.
I worked on a hackathon project to update readmes based on PRs, and it feels very doable. The developer experience is the hardest part... we did a Github Action that would open a PR for README changes, but it's a little slow to edit the PR if any changes are needed and it feels uncomfortable to put API keys into a Github Action.
If you're curious, I've been updating it a little since the hackathon: https://github.com/ktrnka/update-your-readme The readme was mostly generated by the tool itself as we did PRs to build it.
It'd be funny/awesome if the AI can find usage scenarios not thought of by the developer. E.g. period trackers ending up being a tool for prosecution of women in misogynistic regimes...
Once you have created your README, you might want to consider using a tool that I'm currently working on. I'm focused on fixing the "garbage in, garbage out" problem for RAG by focusing on spelling and grammar, among other things. You can see an example of the tool in action at
As someone french the website translation which I assume automated is very off-putting - what works well in english ("our simple editor") feels to me very strange and icky for a product in my mother tongue ("notre simple éditeur" / "votre projet").
I'd have translated it as "Un éditeur simple pour rapidement ajouter et personnaliser toutes les sections d'un fichier README" without involving directly the business and the end-user but rather keeping things impersonal.
Here are the traditional best practices of how README files should look:
“The distribution should contain a file named README with a general overview of the package:
• the name of the package;
• the version number of the package, or refer to where in the package the version can be found;
• a general description of what the package does;
• a reference to the file INSTALL, which should in turn contain an explanation of the installation procedure;
• a brief explanation of any unusual top-level directories or files, or other hints for readers to find their way around the source;
• a reference to the file which contains the copying conditions. The GNU GPL, if used, should be in a file called COPYING. If the GNU LGPL is used, it should be in a file called COPYING.LESSER.”
i make these headings and write down the answers:
too often i see things skip the "what is it" partI would also say in the "what is it" part that projects intended for a broad audience should avoid jargon as much as possible. It's frustrating in my experience to have to google several acronyms before I can even tell what the purpose is. (Security projects/programs are notorious for using way too many acronyms for example)
My rule for writing documentation is as follows: first use of a commonly abbreviated term is written in its complete form, with the acronym or short form in parentheses. Then, the rest of the text in that same page can freely use the shorter form as needed.
So "the File Transfer Protocol (FTP) is bla bla... When using FTP, remember to bla bla..."
I think that's the most structured and correct way to introduce an acronym. Another style is to use "short form (long)" but "long form (short)" feels better to me (although I'm not a native speaker so maybe I got it the other way around!).
Your method is the most common I’ve seen. I also come across this style often:
> …using the File Transfer Protocol, or FTP.
A few more more, depending on the nature of the project and one's goals:
It would be nice if the app would allow us to save templates (no need to get fancy just via URL params e.g. for the above it would be something like:`?sections=title&Desc,installation,runLocally,Support,Authors,Ack,usageExamples`
That way we could just generate a 'template' that we can share/save etc
I appreciate it when there is also a "License" section in the README itself.
Sometimes they skip the how to install it and how to use it part too...
I would call it "an easy way to create a very full featured README" because it's not easier than just loading a snippet or template in ones text editor, but it does offer a very easy way to add specific sections and to customize them.
The "Get Started" button goes right to the editor with three panes: list of sections to include, plain text editor for the current section, and rendered preview. There's no sign up, and the results can be downloaded directly. Very nicely done little app.
I felt the default sections were missing something, so I easily created this:
There, perfect!What does this tool give you that a regular markdown editor (like the one available at GitHub ) doesn't? Suggested sections? It seems like just another markdown editor to me but I'm probably missing something.
I glanced and I don’t see anything you don’t. Just give me a list of suggested headings and a plaintext editor. All this does (as far as I can tell) is save you from typing the headings yourself. If using markdown, there’s some additional formatting being applied (which I’m not saying isn’t handy), but really, who needs a website to do this?
It's a markdown editor with templates for common Github README pages. That's useful, even if it isn't (so far) technically all that complicated. I poked around it and feel like I would probably end up with a better README using this than if I just threw it together in Emacs. That's interesting.
I got the same impression. I think a bullet list reminder if useful Readme sections would be just as useful
How is this "easiest"? Could have only been a template of readme where you could fill whatever fits your need.
This is more like a UI around a template.
I don't understand either why you would need a whole web site to remember "Readme, Usage, Setup, Credits, Release notes, etc."
Feel free to write whatever you want. People forgot (or they are too young) that old READ.ME files were literally free form (with ASCII logos and stuff) and didn't bother with such details.
It's a Github-ism. Github renders a Markdown-formatted readme file as the "front page" of a Git repository.
I used to try do hard with READMEs. Nowadays on my internal tooling I put a few helpful commands, screenshots (my goodness the amount of programs on GitHub without a screenshot of what it does or how it looks), and some info on file formats. I've found that gets me most of the way with minimal effort, vs a very well formatted, nicely laid out, etc etc which takes so long I run out of time for the crucial stuff. Maybe it'd be different if not every user was a 3 minute walk from me.
Related:
Readme.so – Easiest Way to Create a Readme - https://news.ycombinator.com/item?id=27006740 - May 2021 (64 comments)
Readme.so – Easiest Way to Create a Readme - https://news.ycombinator.com/item?id=26919495 - April 2021 (2 comments)
What I usually do is:
Title
AI Generated image serving as a Logo/social preview/etc Badges(I really want 88x31 to be a thing again!)
Quote(I usually try to find a quote for every heading, the way books used to for chapters)
Elevator pitch, 1 or two paragraphs should be enough to know if the project is relevant to you.
Heading (Add an emoji to your headings to make it feel like a proper git project)
Install instructions. If this takes more than a paragraph I assume your project is tinkerers-only stuff that's going to need maintenance, so I like to show off how few steps are needed.
The quotes are mostly flavor/Easter eggs, but they do have a function breaking up the wall of text feeling, as a more fun alternative to whitespace that also acts as a visual marker with a recognizable texture.
OT: I'm looking forward to an AI tool that can look at an entire project and produce documentation for it. Then look at PRs, stories, and other project documents and understand how the project is changing and keep the documentation up to date.
I worked on a hackathon project to update readmes based on PRs, and it feels very doable. The developer experience is the hardest part... we did a Github Action that would open a PR for README changes, but it's a little slow to edit the PR if any changes are needed and it feels uncomfortable to put API keys into a Github Action.
If you're curious, I've been updating it a little since the hackathon: https://github.com/ktrnka/update-your-readme The readme was mostly generated by the tool itself as we did PRs to build it.
It'd be funny/awesome if the AI can find usage scenarios not thought of by the developer. E.g. period trackers ending up being a tool for prosecution of women in misogynistic regimes...
Once you have created your README, you might want to consider using a tool that I'm currently working on. I'm focused on fixing the "garbage in, garbage out" problem for RAG by focusing on spelling and grammar, among other things. You can see an example of the tool in action at
https://app.gitsense.com/microsoft/TinyTroupe?doc=9bc6270618
This will be open sourced and I hope to have source available before the end of this month.
As someone french the website translation which I assume automated is very off-putting - what works well in english ("our simple editor") feels to me very strange and icky for a product in my mother tongue ("notre simple éditeur" / "votre projet"). I'd have translated it as "Un éditeur simple pour rapidement ajouter et personnaliser toutes les sections d'un fichier README" without involving directly the business and the end-user but rather keeping things impersonal.
API Reference as an example is a bit odd. Shouldn't this be auto-generated or be part of the docs in the code?
It would be a great way to show a few calls as an example of the API, then have a link to the auto-generated doc.
Echo “read this” > readme.md
I've found that the easiest way is to use AI to generate the README.
ofc you'll get downvoted bec "AI"!!
But yes, just dump the code into gemini and ask for a github flavored readme and you're 90% there
The last 10% being replacing all the words with ones that are useful to the reader.
No one needs this
Here are the traditional best practices of how README files should look:
“The distribution should contain a file named README with a general overview of the package:
• the name of the package;
• the version number of the package, or refer to where in the package the version can be found;
• a general description of what the package does;
• a reference to the file INSTALL, which should in turn contain an explanation of the installation procedure;
• a brief explanation of any unusual top-level directories or files, or other hints for readers to find their way around the source;
• a reference to the file which contains the copying conditions. The GNU GPL, if used, should be in a file called COPYING. If the GNU LGPL is used, it should be in a file called COPYING.LESSER.”
— GNU Coding Standards, <https://www.gnu.org/prep/standards/html_node/Releases.html#i...> (May 26, 2024)
“Good things to have in the README include:
1. A brief description of the project.
2. A pointer to the project website (if it has one)
3. Notes on the developer's build environment and potential portability problems.
4. A roadmap describing important files and subdirectories.
5. Either build/installation instructions or a pointer to a file containing same (usually INSTALL).
6. Either a maintainers/credits list or a pointer to a file containing same (usually CREDITS).
7. Either recent project news or a pointer to a file containing same (usually NEWS).”
— Software Release Practice HOWTO, <https://tldp.org/HOWTO/Software-Release-Practice-HOWTO/distp...> (Revision 4.1)
(Repost of <https://news.ycombinator.com/item?id=36776684>)