Poor doc organization

[jamesplease]

As a newcomer I'm finding navigating the docs to be a bit of a nightmare. Three distinct problems lead to this:

1. The table of contents is not in the same order as the documentation themselves. For instance, Elements is the first thing in the ToC but Snap starts off the documentation. As a newcomer, this makes it really difficult to scroll through the docs manually because I have no idea what comes before or after the section I'm on.
2. The next thought you might have is...just use the table of contents! Well, this is super funky, too. Some top-level sections have no associated fragment identifier, so clicking the area does nothing. Matrix is an example of this.
3. Okay, so...you can't scroll to navigate, and you also can't click the section headers. Maybe you can click the first item in the section to get to the top? Nope! Because the table of contents is alphabetically sorted, but the order on the page is randomly sorted or something.

Can this be fixed? I'm willing to make a PR. It would do three things:

1. Add section headers for everything, even if there's nothing to include under the header except the first subheader
2. Sections in the ToC match the order in the docs themselves
3. Subsection order matches the order in the docs themselves

[ibrierley]

Previously you could click on the right arrow next to the heading in the doc above the section for each method (it appears when you hover the title of the method), which would take you to https://github.com/adobe-webplatform/Snap.svg/blob/master/src/svg.js#1705 line 1705 for example. However I note that doesn't automatically do that sometimes, not sure if thats a browser thing or what thats changed, as it did seem to used to work.

[arieljake]

I'm finding the docs to be a challenge as well, and would be willing to contribute to a solution...have been looking for something ideal to use as a reference.

how about: https://stripe.com/docs/api

[leeoniya]

https://github.com/adobe-webplatform/Snap.svg/blob/master/src/svg.js#1705 should instead be https://github.com/adobe-webplatform/Snap.svg/blob/master/src/svg.js#L1705

[subhog]

I'll add that it's terrible that the table of contents is anchored to the top of the page and thus is lost whenever I click something. It should float on the side and have independent scrolling. The old Raphael documentation, while not perfect, was way better.

[0x80]

See also #104. I created #444 as a workaround for myself to browse the docs locally on my machine.