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.
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
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.
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.
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...
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 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.
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.
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)
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.
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...
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
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>)