Would appreciate some more info in CONTRIBUTING.md

[LiquidFun]

When creating the previous snippet I was not sure about a couple of things:

• What is is this after every snippet title (###) in the README: <!-- Example ID: 30f1d3fc-e267-4b30-84ef-4d9e7091ac1a --->? Should it be added manually or can it be ignored when creating new snippets?
• Where should new snippets be added? Top/bottom of section, doesn't matter?
• What's the difference between the sections (the first two feel very similar)?
• Before the table of contents it says that markdown-toc -i README.md --maxdepth 3 was used to create it. The pip package markdown-toc does not contain either -i or --maxdepth flags. Which package is meant, or what version of that package?
• Should the new table of contents entry for the snippet be created with the above command or created manually (in case the above command does more than only add the entry)?

Would be nice if these things could be explained with a sentence or two each in the contributing document. Or if they are explained somewhere already, perhaps link to them in CONTRIBUTING.md?

Thanks! :)

[satwikkansal]

Hi @LiquidFun

All the questions seem genuine to me, and I'll update the Readme for these. Thanks for taking out time to put them together. :)

I'll also answer them here.

What is is this after every snippet title (###) in the README: <!-- Example ID: 30f1d3fc-e267-4b30-84ef-4d9e7091ac1a --->? Should it be added manually or can it be ignored when creating new snippets?

That's a random UUID, it is used to keep identify the examples across multiple translations of the project. As a contributor, you don't have to worry about behind the scenes of how it is used, you just have to add a new random UUID to new examples in that format.

Where should new snippets be added? Top/bottom of the section, doesn't ?

There are multiple things that are considered to decide the order (the dependency on the other examples, difficulty level, category, etc). I'd suggest simply adding the new example at the bottom of a section you find more fitting (or just add it to the Miscellaneous section). Its order will be taken care of in future revisions.

What's the difference between the sections (the first two feel very similar)?

The section "Strain your brain" contains more contrived examples that you may not really encounter in real life, whereas the section "Slippery Slopes" contains examples that have the potential to be encountered more frequently while programming.

Before the table of contents it says that markdown-toc -i README.md --maxdepth 3 was used to create it. The pip package markdown-toc does not contain either -i or --maxdepth flags. Which package is meant, or what version of that package? Should the new table of contents entry for the snippet be created with the above command or created manually (in case the above command does more than only add the entry)?

We use the [markdown-toc][https://www.npmjs.com/package/markdown-toc] npm package to generate ToC. It has some issues with special characters though (I'm not sure if it's fixed yet). More often than not, I just end up inserting the toc link manually at the right place. The tool is handy when I have to big reordering, otherwise just updating toc manually is more convenient imo.