[Epic] Improve docs for indexes
Nobody has claimed this yet.
- Dominant language
- CSS
- Stars
- 15
- Forks
- 49
- Avg merge
- 1d 13h
- Merged PRs (30d)
- 3
Description
Currently, docs for indexes are scattered across multiple places. For example, there is no single place where a reader can find all the examples of working with different types of indexes: how-to information can be found in Concepts, How-tos, API, and so on.
This issue is the next step after https://github.com/tarantool/doc/pull/3562 and suggests the possible solutions for improving docs for Indexes:
- It would be convenient to have all 'How-to' information for indexes in one place - the Using indexes topic. We can move the following information to this topic:
- Examples from the API docs: Examples for box.index
- Examples from
space_object:create_index(): Examples - Examples from Concepts for RTREE: https://www.tarantool.io/en/doc/latest/concepts/data_model/indexes/#rtree-indexes
- Examples from Concepts for BITSET: https://www.tarantool.io/en/doc/latest/concepts/data_model/indexes/#bitset-indexes
- Move all How-to examples to the
code_snippetsfolder and reference them usingliteralinclude. When possible, make them look uniformly with the currentcode_snippets/indexessamples. - Create new testable samples for all members of the box.index submodule. The https://github.com/tarantool/doc/pull/3562 PR added examples for
selectandaggr(count, min, max) methods. - Try to reuse samples created in the previous step in the CRUD examples topic. To do this, we need to add the testable samples for CRUD operations on spaces (which might duplicate the examples for the primary index to some extent). Index-related examples for spaces can be reused here:
- Move the information about iterators from the pairs method description to Concepts because iterators can also be used in other methods (for example,
select). Note: currently, there is no link from Iterators to Collations although they are directly related. - Add the links from the CRUD API members (for example, select) to the Complexity factors section.
As the result, we'll have a single How-to topic that shows how to work with indexes. This topic should have more clear structure, better distinguish examples for different index types, different CRUD operations, have a separate section for Pagination for better visibility.
Note that currently Google search finds only the Index Concepts topic, so we need to mention the How-to topic in Concepts explicitly.
We also need to take into account the following issues:
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the existing how-to/db/indexes topic, code_snippets/indexes samples, Concepts data_model/indexes and operations topics, the box.index and box_space API pages, CRUD examples, and PR #3562. Done means the index documentation has a coherent How-to structure, reusable testable samples, the requested cross-links, and clearer coverage of index types, CRUD operations, iterators, and pagination.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- lua
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 32/100