Table of Contents discussion

[RichardLitt]

@tunnckoCore, here:

Except one requirement in "Table of contents":

Must be at least one-depth: must capture all ## headings.
In my repos i my name and badges/links to me as last h2 heading.

That's cool; for reference, see this README. I don't think this is the right approach, though - it's something I haven't seen much before, and I don't think it adds anything to the repo by having these be sections. So, I don't think I will adopt this. The creator's name isn't actually relevant to the code, and doesn't help with using it.

---

@rstacruz, here:

Curious: Would it be prudent to require a ToC even for the shortest of readmes? What led to the decision to require ToC's?

I think that ToC's make it much, much easier to get - at a glance - what is in the readme when it is long. For shorter ones, I don't think it adds too much noise, and it is still useful for simply not having to think about scrolling. A lot of people work on GitHub on small screens - my mac is a puny 5 inches high. Having a ToC helps more than it detracts. Keeping it to second-level headers only is useful. This is a style decision.

[tunnckoCore]

get-comments is not good example, but yea, last heading to be me is too personalized. just don't see sense on license as last heading.

[RichardLitt]

Yeah. The License as the last section is just what I've seen as a standard, and it makes sense to me.

[RichardLitt]

Reopen as needed.