Skip to content

Restructure docs, stage 2 #3116

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 21 commits into from
Sep 19, 2022
Merged

Restructure docs, stage 2 #3116

merged 21 commits into from
Sep 19, 2022

Conversation

patiencedaur
Copy link
Contributor

@patiencedaur patiencedaur commented Aug 26, 2022 •
edited
Loading

Resolves #2987
Resolves #2805

Rebase this often!

Plan:
https://www.notion.so/tarantool/Tarantool-CE-c075d0db9ce24893beca704c145ae501#a89e84e55afe45f091df87be9a32a884
(internal document)

  • Move Access control to Administration (1sp)

  • Create new Concepts section

  • Application server -> Concepts, How-to, other sections (5sp)

  • Data model -> Concepts, How-to, Reference (5sp)

  • Indexes -> Concepts, How-to (3sp)

  • Sharding -> Concepts, Administration, Reference, How-to (5sp)

  • Replication -> Concepts, other sections (5sp)

  • Fill the new Concepts section with all the necessary info (audience: product teams, analysts) (1sp)

      - Application server
  - Data model
  - Transactions
  - Sharding
  - Replication
  - Binary protocol: top-level page with a link to https://www.tarantool.io/en/doc/latest/dev_guide/internals/box_protocol/
  - Storage engines

  • Replace links where needed (1sp)

  • Add links to Overview (1sp)

  • Transfer translations (1sp)

  • Add redirects (1sp): https://github.com/tarantool/tarantool.io/pull/1296

@patiencedaur patiencedaur self-assigned this Aug 31, 2022
@patiencedaur
Copy link
Contributor Author

patiencedaur commented Aug 31, 2022 •
edited
Loading

Redirects

App server

  • - /book/box/authentication -> /book/admin/access_control
  • - /book/app_server/launching_app -> /how-to/app/launching_app
  • - /book/app_server/creating_app -> /how-to/app/creating_app
  • - /book/app_server/cookbook -> /how-to/app/cookbook
  • - /book/app_server/using_ide -> /how-to/app/using_ide
  • - /book/app_server/installing_module -> /book/admin/modules
  • - /book/app_server/reloading_module -> /book/admin/modules
  • - /book/app_server/contributing_module -> /dev_guide/contributing_module
  • - /book/app_server/luajit_memprof -> /reference/tooling/luajit_memprof
  • - /book/app_server/luajit_getmetrics -> /reference/tooling/luajit_getmetrics

Tooling

  • - /reference/tarantoolctl -> /reference/tooling/tarantoolctl
  • - /reference/tt_cli/* -> /reference/tooling/tt_cli/*
  • - /reference/interactive_console -> /reference/tooling/interactive_console

Data model

  • - /book/box/data_model/ -> /concepts/data_model

Indexes

  • /book/box/indexes -> /concepts/data_model/indexes

Sharding

  • /reference/reference_rock/vshard/vshard_quick/ -> /how-to/vshard_quick
  • - /reference/reference_rock/vshard/vshard_admin/ -> /book/admin/vshard_admin/

Triggers

  • - /book/box/triggers/ -> /concepts/triggers

Transactions

  • - /book/box/atomic -> /concepts/atomic

Storage engines

  • - /book/box/engines/* -> /concepts/engines/*

Replication

  • - /book/replication/index -> /concepts/replication/index
  • - /book/replication/repl_architecture/ -> /concepts/replication/repl_architecture/
  • - /book/replication/repl_sync/ -> /concepts/replication/repl_sync/
  • - /book/replication/repl_leader_elect/ -> /concepts/replication/repl_leader_elect/
  • - /book/replication/repl_bootstrap/ -> /how-to/replication/repl_bootstrap/
  • - /book/replication/repl_add_instances/ -> /how-to/replication/repl_add_instances/
  • - /book/replication/repl_remove_instances/ -> /how-to/replication/repl_remove_instances/
  • - /book/replication/repl_monitoring/ -> /book/admin/replication/repl_monitoring/
  • - /book/replication/repl_recover/ -> /book/admin/replication/repl_recover/
  • - /book/replication/repl_reseed/ -> /book/admin/replication/repl_reseed/
  • - /book/replication/repl_problem_solving/ -> /book/admin/replication/repl_problem_solving/

@patiencedaur patiencedaur mentioned this pull request Aug 31, 2022
Closed
@patiencedaur patiencedaur force-pushed the restructure-docs-2 branch 4 times, most recently from 4df2ff7 to ad22191 Compare September 11, 2022 09:58
@patiencedaur patiencedaur force-pushed the restructure-docs-2 branch 2 times, most recently from 9e93b73 to b5a23ba Compare September 12, 2022 07:41
@patiencedaur patiencedaur force-pushed the restructure-docs-2 branch 3 times, most recently from 3deeb0e to 4155632 Compare September 13, 2022 09:55
@p7nov
Copy link
Contributor

p7nov commented Sep 14, 2022

That's an impressive work!
I've looked through changes and checked that nothing is lost and the deployment looks OK in general. Didn't check the new text thoroughly.

However, I've got one concern about repeating headings in different top-level sections. We have Replication and Sharding in How-to, in Concepts, and in Administration. This already affects the search: when you type "sharding", you get three results with the same heading. This may be confusing. Moreover, I'm not sure how this will affect SEO. Perhaps we can think of more specific headings.

@patiencedaur patiencedaur force-pushed the restructure-docs-2 branch 5 times, most recently from 4175260 to f2a597f Compare September 15, 2022 14:01
p7nov
p7nov approved these changes Sep 16, 2022
View reviewed changes
Copy link
Contributor

@p7nov p7nov left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@patiencedaur
Copy link
Contributor Author

patiencedaur commented Sep 16, 2022 •
edited
Loading

For some reason the :fullwidth: directive cannot remove the headers in the right menu. After this PR is merged, we need to check with the frontend developers:

@patiencedaur
Put the Access control page in the Admin guide
e0dbf94 
* Remove redundant Authentication page
@patiencedaur
Add Concepts page stub
af3c5cc
@patiencedaur
Split the Application server section
dc7bff0 
Move the content to different chapters, save some content for the Concepts section.

* Tutorial on pokemons (Creating application): How-to
* Developing with IDE, Cookbook recipes: How-to
* Module installation and reload: Admin guide
* Module contribution: Dev guide
* Create a Tooling section in the Reference chapter
* Move console tools to the Tooling section
* LuaJIT tooling: Reference/Tooling
* Concepts: early draft
@patiencedaur
Fix console warnings
e2bd2bd
@patiencedaur
Rework the Data model section
943ca66
@patiencedaur
Separate the sequences section into a tutorial
d35423b
@patiencedaur
Incorporate Indexes section
ede5a4e
@patiencedaur
Fix some build warnings
4bed21e
@patiencedaur
Rework the Sharding section
b77537b 
* Overview & Architecture -> Concepts
* Quick start -> How-to
* Sharding administration -> Administration
@patiencedaur
Add Triggers to Concepts
6aa8127
@patiencedaur
Rename sharding guide for clarity
5bd0539
@patiencedaur
Move Transactions section to Concepts
a0d26b1
@patiencedaur
Add Storage engines to Concepts
6446762
@patiencedaur
Move Replication to Concepts
b5487ed 
* Remove unused examples from 2019
  Also remove unused files from conf.py exclusions

* Fix some build warnings

* Move some replication guides to Administration

- Monitoring a replica set
- Reseeding a replica
- Recovering from a degraded state
- Resolving replication conflicts

* Split repl_sync and repl_leader elect to Concepts and How-to

* Format by style guide

* Fix heading levels

* Move 'Server startup with replication' to Internals

* Move orphan status to internals

* Move Replication internals translation
@patiencedaur
Move tt cli coredump doc to Tooling
acc0443
@patiencedaur
Add links to Overview
6d55bb6
@patiencedaur
Resolve file conflicts
2828fdb
@patiencedaur
Remove a broken link
6637521
@patiencedaur
Name similar sections in How-to and Administration differently
edf93b1
@patiencedaur
Remove duplicate headings from the Concepts index page
38f6c6c
@patiencedaur
Keep the header formatting but avoid right panel subheadings
8a57851
@patiencedaur patiencedaur merged commit 07cb38f into latest Sep 19, 2022
@patiencedaur patiencedaur deleted the restructure-docs-2 branch September 19, 2022 07:21
@patiencedaur patiencedaur mentioned this pull request Oct 3, 2022
Closed
22 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@p7nov p7nov p7nov approved these changes

@xuniq xuniq xuniq approved these changes

@veod32 veod32 Awaiting requested review from veod32

@NickVolynkin NickVolynkin Awaiting requested review from NickVolynkin

Assignees

@patiencedaur patiencedaur

Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Add the umbrella section Concepts Make the Getting Started section more intuitive
3 participants
@patiencedaur @p7nov @xuniq