tarantool / tarantool/doc

[Epic] Improve docs for indexes

Open
#3,572 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

epic
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:

  1. 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:
  2. Move all How-to examples to the code_snippets folder and reference them using literalinclude. When possible, make them look uniformly with the current code_snippets/indexes samples.
  3. Create new testable samples for all members of the box.index submodule. The https://github.com/tarantool/doc/pull/3562 PR added examples for select and aggr (count, min, max) methods.
  4. 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:
  5. 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.
  6. 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.