The current editable template is a great start. It's right there and you just have to edit it, like you do with your README.md in your editor. (That's a little nerdy, but not elitist, so i would keep that design. I think programmers love it!) You don't have to install anything and have a preview next to it.

We should extend it in a way so it still feels this lightwight.

I like the idea to have sections that a readme should have and optional ones. A text above the section descriptions should explain that.

I also like to have a common section order that a readme should follow. This spec is a good starting point.

I suggest a design where you can enable and disable sections with switches like these. sections a readme should have are enabled by default. When enabled, the new sections appear in the editor box. A section consists of it's heading and everything until the next section heading including an empty line. When you disable a section that you already edited, the content should be saved locally, so it's added again when re-enabled.

Reloading the site or using a reset button resets the template editor and section switches.

I'm not a designer or UX specialist, so i would like to hear the opinion of one. I'm also no JS programmer, so i will not implement it. There is probably someone who would like to do that.

Here are different Examples:

• https://michaeldyrynda.github.io/readme-generator/
• https://generatewp.com/plugin-readme/

What do you think so far?

The template on the main website implicitly recommends the use of the MIT License.

In my opinion, developers should be encouraged to perform some research on the license they wish to use (especially when MIT can actually be very harmful to "open-source"). Currently, the template does not encourage this good practice.

Furthermore, the template(s) must not encourage developers to use the MIT License without understanding the negatives and positives of said license. Perhaps an external website would be better to explain this.

Editor is not active right now on opera 66.0.3515.72

It is not related with cache or etc.

This site has gotten good traction. According to Google Search Console, it now has an average search results position of 8 for queries like "readme", "create readme.md", and "readme template". It is also trending towards 3,600 hits a month, according to Google Analytics.

Now's a good time to come up with some ideas for making the site better. Some that I can think of off the top of my head:

• Translate the website. Crowdin might be a good solution. They have a free plan for open source projects, and Docusaurus uses them. LingoHub and PhraseApp also have free options for open source.
• Do a check for accessibility. I don't have any experience with this, so it'll be a good learning opportunity.
• Create an interactive README generator.
• Show examples for individual sections or maybe even entire READMEs.

Show a few stackoverflow style code examples if applicable.

• 1/3 of programmers prefer reference docs
• 1/3 of programmers prefer tutorials
• 1/3 of programmers prefer cohesive code examples

Why? stops 1/3 of people instantly hitting the back button.

.. and perhaps how long they take and whether they pop a browser (Selenium, etc).

I have been adding a "Credits" section to my repos example and while it is definitely optional, I think it is a nice addition and good karma.

If you are open to it, I'll make a PR that adds it to the homepage and example template. And add it to this repo's README!

Aids adoption; stops ppl hitting the back button so quickly.

The " Try ReadMe.com " text in red, is overlaying with the description, when viewed on a smaller screen.

I was wondering if support for emojis in the preview would be a thing?

I saw many developers have in their repositories with emojis. It would be awesome if we could get a preview of the GitHub emoji.

What's your opinion on this?

In a markdown table cell, the escape character to use | is ignored.

The table that should render like this:

Instead renders like this:

...but with an extra cell after the second row.

To reproduce, place this code in the editable markdown input:

| col1 | col2 | col3 |
| --- | --- | --- |
| yes\|no | maybe | sometimes |

I've come up with a list of example readmes. I'll add these in a new section of the website along with a short description of each one and what you can learn from it.
Here are the READMES:
https://github.com/sindresorhus/pageres
https://github.com/akashnimare/foco
https://github.com/ai/size-limit
https://github.com/sr6033/lterm
https://github.com/amitmerchant1990/electron-markdownify

If you paste this you will see that the input box is so thin and tall that you can't read anything.
https://gist.github.com/axi92/057a3cd5c5d514ed4b1555f89b73465a

I want to discuss the sections and hope we can agree on sections, if they are optional or recommended to have and their order. The goal should be to have such generic headings that any kind of open source project can use. The description should explain what is important in that section.

When we have it, we can use the sections one should use in the editable template (until we have an interactive generator #15) and explain every section under it.

Why i think we have to rework this: Currently it's not consistent. In the descriptions, Installation and Requirements are different sections, in the template Requirements is a subitem of Installation (what makes sense to me). I think Features belong in the description. Development belongs to Contributing or Contributing.md. "Contributing back" is not a common title for that section.

Let's start with the sections a readme should have.

Sections

Name

Status: required

Description

Status: required

Installation

Status: required

Usage

Status: required

Contributing

Status: required

License

Status: required

It's not much different to the current one. Only "Development" was removed.

I'm unsure about a short description.

https://github.com/RichardLitt/standard-readme/blob/master/spec.md#short-description

I don't like the style GitHub renders it. (also others think so, see discussion in RichardLitt/standard-readme#22) But i think it's good to have it because it gives a very short description about the project. You should also use it for GitHub description and package managers, like the spec says. When you have that in your readme, you can just copy it and it's consistent. It might not be needed if the project name sais everything.

What do you think?

Sure, you show a pip install. But mention apt-get, homebrew, nuget for Windows/Mac/Linux libraries too.

Have you considered adopting the Standard Readme Style Spec by @RichardLitt?

Practical that would mean having the required sections in your editable template. (see minimal-readme.md) Add your example content again.

After that, explain each section like here https://github.com/RichardLitt/standard-readme/blob/master/spec.md#sections

You can mention that it follows the Spec (with link) that members of the open source community has worked out and that one can add the badge if one follows it.

Your sections and their order are already very similar to the Standard Readme Style Spec, so this might not be too complicated. You have some additional, optional sections that make sense to me, like Visuals, Support, Roadmap and Project status, so you would need to collaborate with the other project to find consent to add them or remove them.

Would you like going this way? I could propose a Pull Request.

I opened a similar issue on their repo. (RichardLitt/standard-readme#82)