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.

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.

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.

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.

Echo “read this” > readme.md

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

too often i see things skip the "what is it" part

API Reference as an example is a bit odd. Shouldn't this be auto-generated or be part of the docs in the code?

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.

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!

There, perfect!

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.

No one needs this

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.