Improve our README structure

nteract / hydrogen

:atom: Run code interactively, inspect data, and plot. All the power of Jupyter kernels, inside your favorite text editor.

https://nteract.gitbooks.io/hydrogen/

MIT License

3.92k stars 333 forks source link

Improve our README structure #654

Closed lgeiger closed 7 years ago

lgeiger commented 7 years ago

Our README has a lot of valuable information. Though it's a bit unstructured at the moment. I think we should either move a few sections into separate files or provide a table of content on the top.

For example: https://github.com/RichardLitt/standard-readme https://github.com/jakubroztocil/httpie

willingc commented 7 years ago

Here's another good example: https://gist.github.com/PurpleBooth/109311bb0361f32d87a2

lgeiger commented 7 years ago

@willingc Thanks for the link!

BenRussert commented 7 years ago

To start the ball rolling I added a "Contents" header with links to each section to my fork.

I think this small step helps organize a fairly lengthy README.

willingc commented 7 years ago

@BenRussert Looks good and the extra navigation helps.

Two small suggestions:

Move the GIF up higher under so folks can see it without scrolling. I would grab the sentence about the Medium blog post with the image. So it would flow:
- Title
- badges
- The intro sentence "This package lets you run your code ..."
- "Checkout our Medium blog post to see what you can do with Hydrogen."
- GIF
- Contents
- Background (less what was moved higher)
At the very end of the file, it might be nice to add a "Return to top" link that brings you to the contents or top of file.

Nice job 👍

BenRussert commented 7 years ago

@willingc Great points. I made these changes and opened a pr.