Re-structure Readme using a TOC #6955
Conversation
jeffwidman
force-pushed
the
re-order-readme-using-intuitive-TOC
branch
10 times, most recently
from
6fef23c to
8233216
Compare
| Dependabot and Dependabot Core started life as [Bump][bump] and | ||
| [Bump Core][bump-core], back when Harry and Grey were working at | ||
| [GoCardless][gocardless]. We remain grateful for the help and support of | ||
| Dependabot and Dependabot-Core started life as [Bump][https://github.com/gocardless/bump] and |
There was a problem hiding this comment.
Using "Dependabot Core" seemed ambiguous to me... we always refer to it as a single compound word, so I renamed it to "Dependabot-Core" everywhere...
| 2. Get the [development environment running](TODO:hyperlink). | ||
| 3. Make your feature addition or bug fix. | ||
| 4. Add [tests for it](TODO:hyperlink). This is important so we don't break it in a future version unintentionally. | ||
| 5. Send a pull request. The tests will run on it automatically, so don't worry if you couldn't get them running locally. |
There was a problem hiding this comment.
This is duplicated here and in the Contributing section... Kinda like to drop one of them, but not sure which one... I do like having a contribution workflow front and center on the readme.
| To run all of Dependabot Core, you'll need Ruby, Python, PHP, Elixir, Node, Go, | ||
| Elm, and Rust installed. However, if you just wish to run it for a single | ||
| language you can get away with just having that language and Ruby. | ||
| Skip the wait by pulling the pre-built image for the ecosystem you want to work on. The image name uses the [YAML ecosystem name](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#package-ecosystem) |
There was a problem hiding this comment.
We used to have this shortcut buried further down, but we want new contributors to get going as fast as possible, so highlighting how to pull the image as the first step will save them 5-10 mins and lead to a much more pleasant first experience. At least for me it did.
jeffwidman
force-pushed
the
re-order-readme-using-intuitive-TOC
branch
from
8233216 to
504d155
Compare
|
I like the table of contents idea, but it turns out README files already have one? https://github.blog/changelog/2021-04-13-table-of-contents-support-in-markdown-files/ |
That's awesome, I had no idea that existed. I still think we should have an explicit TOC of the high-level links because it's much more discoverable than the built-in one. I wish they offered a TOC widget that we could embed for those who want an always-visible TOC. Although in this case I have an abundance of headings so that we can deep-link to specific points from issue comments, but many of those are so granular we don't want them in the TOC to minimize noise. |
jeffwidman
force-pushed
the
re-order-readme-using-intuitive-TOC
branch
12 times, most recently
from
7be5f70 to
5b889c3
Compare
Over time the Readme has grown organically by adding new sections as needed. Unfortunately, the length and relative lack of order makes it not very approachable for folks new to the project. So this adds a Table of Contents structured in a way that's more accessible, and then re-orders the content appropriately.
jeffwidman
force-pushed
the
re-order-readme-using-intuitive-TOC
branch
from
5b889c3 to
8c1bf58
Compare
|
Okay, I've addressed all the TODO's, which were mostly missing hyperlinks. Feedback both here and on our internal slack was very positive. I'm sure this can be improved further, but by landing it now we can start deep-linking to various sections when responding to issues. So I'm going to go ahead and merge, and then we can add further refinements in follow-on PR's. |
Over time the Readme has grown organically by adding new sections as needed. Unfortunately, the length and relative lack of order makes it not very approachable for folks new to the project.
So this adds a Table of Contents structured in a way that's more accessible, and then re-orders the content appropriately.
rendered