Sections

[davidak]

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?

[dguo]

I agree with all your points about consistency. "Requirements" should be under "Installation", "Features" can go in the description, and "Development" should be in "Contributing". And yeah, I've never seen "Contributing back". I'm not sure why that came to mind when I made the site.

I'm not a fan of requiring the short description. Sometimes it's nice to have a pithy one-liner; other times, it's just unnecessary. And whether or not it's a blockquote seems like such a trivial detail that I don't see the value in mentioning it. Though I personally don't like the blockquote style either and would just use a single-line paragraph.

[davidak]

Art of README says that a short description is the second section visitors look for after the name. Source That might especially apply for code modules, but maybe also for any other project. It saves peoples time when looking at projects. Is that a good point do add it as required section?

If you still don't like that, we can mention it in the description explanation as optional.

[davidak]

As next step i want to look at the optional sections and rework the section description. I think it would be usefull to use the wiki on GitHub for that. Could you activate it for this repo?

[dguo]

Yeah, a short description makes sense to me as a suggestion rather than an explicit requirement.

And you should be able to edit the wiki now.