i make these headings and write down the answers:
what is it
how do i install it
how do i use it
any "pro-tips"/useful stuff to know
how do i get help (optional)
acknowledgements etc (optional)
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!).
A few more more, depending on the nature of the project and one's goals:
how do I report bugs
how do I build from source
how can I help/contributeIt 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
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?
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.
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!
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.
API Reference as an example is a bit odd. Shouldn't this be auto-generated or be part of the docs in the code?
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.
Echo “read this” > readme.md
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>)
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