Confusion about index types (hash, skiplist, persistent)

[jsteemann]

The "Indexing" section in the manual (https://www.arangodb.com/docs/stable/indexing.html) shows all the different types of indexes.
Clicking on "Persistent indexes", one gets to the page https://www.arangodb.com/docs/stable/indexing-persistent.html.
This page directly at its top states

The persistent index type is considered as deprecated from version 3.4.0 on. It will be removed in 4.0.0. If you use the RocksDB storage engine, you can replace it with a skiplist index, which uses the same implementation.

This is misleading.
The persistent index is deprecated for MMFiles only. For MMFiles the index types "hash", "skiplist" and "persistent" index are actually different index types with different implementations.
However, for the RocksDB engine the "hash", "skiplist" and "persistent" indexes are exactly the same (apart from the type names). So for RocksDB the persistent index is not deprecated.
And as for RocksDB the indexes are all the same, it does not make sense to offer them all. Especially offering a "hash" index for RocksDB that is not even a hash index, or a "skiplist" index for RocksDB that is not a skiplist index makes no sense.
We have already made a UI change in 3.5 and offer only "persistent" indexes in the web UI when creating new indexes with RocksDB. For MMFiles all index types are still present in the web UI.
Now, with "persistent" being the only type of index offered in the web UI, and the manual saying it is deprecated, this leaves the docs in a very confusing state.

I see the following two ways forward:

1. split the indexes section in the manual into a RocksDB-specific and an MMFiles-specific section. Then say for the RocksDB that the index types "hash", "skiplist" and "persistent" are the same internally, and that "hash" and "skiplist" are only there for compatibility reasons with MMFiles.
2. don't split the section, but on each individual index type page explain the differences between RocksDB and MMFiles.

Probably related: #84

[Simran-B]

https://www.arangodb.com/docs/stable/release-notes-new-features35.html#web-interface
https://www.arangodb.com/docs/stable/indexing-index-basics.html#persistent-index
https://www.arangodb.com/docs/stable/indexing-persistent.html

[Simran-B]

Partially solved by e4873fe

Content needs in-depth revision. MMFiles engine deprecation from 3.6.0 on.

[Simran-B]

Remaining issues to be handled as part of indexing chapter refactor https://arangodb.atlassian.net/browse/DOC-38