Better depiction of bits in bit layout. (Also place all api names on left side panel, like java documentation to make it easier/quicker to find them)

[SkybuckFlying]

https://h3geo.org/docs/core-library/h3Indexing/

Problem with "Bit layout of H3Index" table is the non-usage of 1 block per bit.

Instead the entire field is one big block. The colors chosen are also very vague, very hard to see where a block begins and ends.

For example I did not notice initially that digit 10 is actually 1 bits on the bottom row and 2 bits on the row above it.

One cause of this is the usage of hexadecimal and the x in front of it, hexadecimal adds very little to this and confuses more than is worth it, simply decimal usage would have made the table more compact. Now because of 3 letters per box, instead of just 1 or 2, it's unnecessary wide and needs scrolling on a 1600x900 monitor.

Recommendation is to switch to decimal, and use 1 box per bit, and use a legend and letters to depict the bits more clearly. Using both is best. One layout to clearly surround the fields and put the words into them, but also one where the bits are crystal clear placed. I would even go so far as to put a row of offset numbers below each row to make it more practical usefull to quickly find the correct offset, without having to do strange hexadecimal calculations.

In case one wants to only store on depiction, adding boxes around the bits that belong together would be a very recommendation. One big box with black thick lines, and one thin little gray box per letter/bit so that it can clearly be seen that it's one bit.

Better or extra depiction of bit positions:

LEGEND:
. = Reserved
M = Mode
MD = Mode Dependent
R = Resolution
B = Base Cell
DX = D=Digit X=Number

64 BIT DATA FIELD:

        63  62  61  60  59  58  57  56  55  54  53  52  51  50  49  48
0063    .   M   M   M   M   MD  MD  MD  R   R   R   R   B   B   B   B    0048

    47  46  45  44  43  42  41  40  39  38  37  36  35  34  33  32
0047    B   B   B   D1  D1  D1  D2  D2  D2  D3  D3  D3  D4  D4  D4  D5   0032

    31  30  29  28  27  26  25  24  23  22  21  20  19  18  17  16
0031    D5  D5  D6  D6  D6  D7  D7  D7  D8  D8  D8  D9  D9  D9  D10 D10  0016

        15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0
0015    D10 D11 D11 D12 D12 D12 D13 D13 D13 D14 D14 D14 D14 D15 D15 D15  0000

[SkybuckFlying]

I will also include my initial depiction which makes it even easier to see exactly where each field begins and each field ends without any uncertainty, and also it's size without any uncertainty, so it's also worth something, though the bit order is reversed and it uses a horizontal display at the bottom to show it one more time in an ultra compact way: (It may sound strange, but I recommend including all three techniques, the original way, perhaps slightly improved, the one above from me, and even the one below, so that it is crystal clear, each programmer may like one above the other depending on his/her own experiences or need-case)

  Fields and bits and bit positions
  A = Digit 15 = 3 bits = 00..02 bit offset
  B = Digit 14 = 3 bits = 03..05 bit offset
  C = Digit 13 = 3 bits = 06..08 bit offset
  D = Digit 12 = 3 bits = 09..11 bit offset
  E = Digit 11 = 3 bits = 12..14 bit offset
  F = Digit 10 = 3 bits = 15..17 bit offset
  G = Digit 09 = 3 bits = 18..20 bit offset
  H = Digit 08 = 3 bits = 21..23 bit offset
  I = Digit 07 = 3 bits = 24..26 bit offset
  J = Digit 06 = 3 bits = 27..29 bit offset
  K = Digit 05 = 3 bits = 30..32 bit offset
  L = Digit 04 = 3 bits = 33..35 bit offset
  M = Digit 03 = 3 bits = 36..38 bit offset
  N = Digit 02 = 3 bits = 39..41 bit offset
  O = Digit 01 = 3 bits = 42..44 bit offset
  P = Base Cell = 7 bits = 45..51 bit offset
  Q = Resolution = 4 bits = 52..55 bit offset
  R = Mode-Dependent = 3 bits = 56..58 bit offset
  S = Mode = 4 bits = 59..62 bit offset
  T = Reserved = 1 bit = 63 bit offset

  bit positions
  0         1         2         3         4         5         6
  0123456789012345678901234567890123456789012345678901234567890123
  AAABBBCCCDDDEEEFFFGGGHHHIIIJJJKKKLLLMMMNNNOOOPPPPPPPQQQQRRRSSSST

[SkybuckFlying]

Finally I would recommend repeating these depictions per mode/type.

So one for H3 Cell Index So one for H3 Edge Index

and so one and then simply replace the legend.

So that it is crystal clear, how each type/mode is stored. It's a bit redundant but leaves no doubt as to how it's stored.

One thing which I find annoying about the H3 documentation is the constantly scrolling back and forth, it takes a lot of time.

Because the table currently is at the bottom, one has to scroll up and down a lot to try and understand grasp it.

It's a tiny little example of "excessive scrolling" but the entire documentation is full of it. Very unfortunate.

Finding anythig is also very hard.

I would highly recommend putting all API function call names on the left side panel, so it can quickly be scrolled up and done and select from it, optionally seperated by group if desired, but should remain alphabetically within the group.

For a good example of how to document a large API see the java documentation example.

[isaacbrodsky]

I've been meaning to break the index modes out into their own pages, I started a PR in #667 to do that.

I agree the scrolling is very unfortunate and we should try to fix that. I think that is exacerbated by a styling issue that prevents the table from ever being full width, although I imagine breaking the table in half horizontally would be easier for more readers.

[douglasg14b]

I made a spreadsheet as a playground that I found made this easier to visualize and understand.

Might be worthwhile as inspiration? Maybe make an index playground in the docs that lets people play with the values and do various conversions & manipulations?

[nrabinowitz]

@douglasg14b We do have a playground-style bit layout explorer on Observable: https://observablehq.com/@nrabinowitz/h3-index-bit-layout

Not sure if we can easily make this part of the docs, but it might be worth trying. I like your layout here, this is a bit nicer than my current notebook and probably worth emulating - thanks!