Add table of contents to README for easier navigation.

tricknotes / ember-cli-rails

Unify your EmberCLI and Rails Workflows

http://thoughtbot.github.io/ember-cli-rails/

MIT License

713 stars 205 forks source link

Add table of contents to README for easier navigation. #435

Closed andrewhavens closed 2 years ago

andrewhavens commented 8 years ago

This PR simply adds a table of contents to the README to make it easier to see at a glance what might be documented, as well as make it easier to navigate to those sections.

seanpdoyle commented 8 years ago

Thanks for submitting this PR @andrewhavens!

I tend to either skim READMEs top to bottom, or cmd + f my way through them, so I don’t think a table of contents would help me much.

Also, like most technical documentation, tables of contents are prone to get out of sync with the rest of the document, and would add additional maintenance overhead.

@thoughtbot/copy-editing: how do most of us feel about README tables of contents?

mjankowski commented 8 years ago

I think once a README is so big that you start to think about needing a TOC, it's a sign that you might need more than just a README, and might want to split up into documents.

In this case, I could see something like:

Keep the intro in the readme
Move the Install, Setup and Mount sections to a doc/USAGE.md file
Move Develop to doc/CONTRIBUTING.md file
Add a doc/DEPLOYMENT.md file for that section
Move the override and other customization stuff into a wiki page or a doc/CONFIG.md file
Leave the support/contib/license/about stuff at the bottom in the README

This way your "table of contents" becomes just like 4-5 links, and is less likely to break.

mike-burns commented 8 years ago

RST format (instead of Markdown) will generate a TOC automatically. (I make use of this here, for example: https://github.com/thoughtbot/guides/pull/419 .)

seanpdoyle commented 8 years ago

@mike-burns that's really useful!

@andrewhavens would you be interested in changing the scope of this PR to translating the README to an RST document?

seanpdoyle commented 8 years ago

I think once a README is so big that you start to think about needing a TOC, it's a sign that you might need more than just a README

@mjankowski I agree.

For this project, though, I don't think we've reached the so big stage just yet.

I'm also a big fan of a single README file that I can cmd + f my way through, so I'm torn.

I think exploring what an RST version of the README would look like is worthwhile.

If the RST syntax is too much of an unfamiliar departure from .md syntax, or if the table of contents doesn't end up being helpful, we could explore breaking the document up.

mike-burns commented 8 years ago

Hat tip to @iwz for telling me about RST's TOC feature.