Comments (6)
+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 [email protected]
wrote:
What
Some people have asked me why the Table of Contents is important. Example
orbitdb-archive/orbit#35 (comment).
BackgroundI'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
.
from standard-readme.
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.
from standard-readme.
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.
from standard-readme.
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 π
from standard-readme.
Fair point. Consign long API headers to API.md
.
from standard-readme.
The ToC is now optional if your README is under 100 lines. I think this solves the issue elegantly.
from standard-readme.
Related Issues (20)
- Improvement in License section HOT 1
- Question on Usage section HOT 1
- Question: clarifying on rules for install, usage, and contributing HOT 3
- Installation fails because of missing dependency to opencollective-postinstall HOT 1
- README.cn.md doesn't follow naming convention HOT 8
- Introduce REUSE compliance/compatibility HOT 1
- ζ¨ε₯½οΌθ½εδΈδΈͺζ°ζθ½ηζηζη¨εοΌ
- cat: spec.md: No such file or directory HOT 1
- README, Markdown and other formats HOT 1
- It's a good markdown file HOT 1
- Create a logo for Open Collective
- The "Install" section may not seem right for deployable websites HOT 2
- Does this project comply with standard-readme HOT 1
- Table of Contents Built in to GitHub HOT 2
- Demo
- Some links in the maximal example are broken HOT 4
- Add support for CHANGELOG.md? HOT 2
- Add a Credits/Thanks/Acknowledgements section HOT 6
- Examples use "contributing" which results in an error HOT 3
- Chinese translation HOT 3
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
π Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. πππ
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google β€οΈ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from standard-readme.