The Existence of a Table of Contents

[RichardLitt]

What

Some people have asked me why the Table of Contents is important. Example.

Background

I've been getting some pushback about table of contents being mandatory. For small READMEs with minimal sections, I can understand why this is a friction point. The Table of Content takes up visual space.

However, for longer READMEs, I think a Table of Contents is super important. It allows the reader to know what sections are included in the README at a glance, normally without scrolling down, unless the reading window is small (and, if it is small, a Table of Contents can help signpost whether it is worth scanning to the end or not).

I suspect that most of the time a new module is discovered, it is discovered on GitHub these days - the Table of Contents provides an easy way to navigate a README.

[jbenet]

+1 to TOCs they're super useful in big readmes (and should be an error not
to have one I think past a certain character count)

I do agree TOCs for small readmes are not needed.

But for example, id prefer a TOC in orbit's readme cause it's pretty big
and I don't know what's all in it. I don't know the readme as well as
others.
On Thu, Aug 4, 2016 at 10:12 Richard Littauer notifications@github.com
wrote:

What

Some people have asked me why the Table of Contents is important. Example
orbitdb-archive/orbit#35 (comment).
Background

I've been getting some pushback about table of contents being mandatory.
For small READMEs with minimal sections, I can understand why this is a
friction point. The Table of Content takes up visual space.

However, for longer READMEs, I think a Table of Contents is super
important. It allows the reader to know what sections are included in the
README at a glance, normally without scrolling down, unless the reading
window is small (and, if it is small, a Table of Contents can help signpost
whether it is worth scanning to the end or not).

I suspect that most of the time a new module is discovered, it is
discovered on GitHub these days - the Table of Contents provides an easy
way to navigate a README.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
#27, or mute the
thread
https://github.com/notifications/unsubscribe-auth/AAIcoe4UOyMIGY15IqNrWcMdm1cnL56Rks5qcfNFgaJpZM4JcvPm
.

[martinheidegger]

A TOC is useful once there are a significant amount of sections. I.e. a small readme doesn't need it. The Standard readme could require a "fold" meaning: There is a section with two up to 4 paragraphs required before the TOC. And the TOC excludes the information before the fold. The TOC should imho. also only be required when there are more than 3 h2's but forbidden before that.

[RichardLitt]

As it currently is, the long description goes before the ToC, and can get rather long - it's not inaccurate to put a subsection in the long description (h3 or h4) and then a few more paragraphs. I think this is fine. I don't want to put a character limit on it, although that may be the right way to go.

I don't want to limit the number of h2s, either, because there's nothing saying you can't have three hundred h3s in one h2. Perhaps an lower character bound of 1000, above which you need to have a ToC.

Lines might be a better metric than characters.

[martinheidegger]

Actually

because there's nothing saying you can't have three hundred h3s in one h2

I think that is worth being an issue itself. This kind of doc would be really badly structured and the structure can be improved to make sense to read 😉

[RichardLitt]

Fair point. Consign long API headers to API.md.

[RichardLitt]

The ToC is now optional if your README is under 100 lines. I think this solves the issue elegantly.