Reorganize tasks #1980
Description
Overview
The User Guides landing page is subtitled
"Task-based guides for common usage scenarios".
This conceptualization as task-based is exactly the right approach to the User
Guide. The execution, however, needs some improvement. The User Guides require
three types of changes to maximize their effectiveness: renaming, rewriting, and
reorganization.
Each of these is dealt with in a different issue. This is the one for reorganizing.
The goals of this issue are to:
- Ensure that the various sections of the User Guide cover all usage scenarios.
- Make the instructions for these scenarios easily findable.
These goals are embodied in these strategies:
- Eliminate redundant information so that searches lead directly to the correct information.
- Organize the remaining instructional information to be use-case oriented.
Reorganize the User Guide:
First, organize by user role, if there are distinct roles.
User roles traditionally are the basis for a "User Guide":
- Admin Guide
- DBA Guide
- Programmer's Guide
- etc.
As I understand it, there are basically three user roles in Vitess:
- Vitess admin
- Database admin
- Application developer
Within roles, organize the tasks around use cases. Don't be afraid to split up
tasks that use the same tool (CLI or other). In other words, pick and choose
commands and actions that server a use case rather than trying to document
everything you can do with the command in one place. (There is a place to
exhaustively document a tool, but that's in the Reference, not a User Guide.)
The existing Vitess User Guides are already partially organized around user
roles, but they can be regrouped. In any case, make the user roles explicit:
Vitess admin:
- Configuration
- Running in production
- Operational
- Migration
DBA:
- VSchema and Query Serving
- SQL statement analysis
- Making schema changes
Application programmer:
- Query serving
- Making schema changes (don't duplicate the section here. Instead provide links
to any tasks that are identical) - Query optimization
(Again, these are my understanding of the Vitess user roles. Adjust the details if
they're different.)
Audience: All
Type: Task
Context
This issue tracks recommended changes resulting from an analysis of the Vitess
documentation commissioned by CNCF. The analysis and supporting documents are
here: https://github.com/cncf/techdocs/tree/main/analyses/0014-vitess under
0014-Vitess.
See the umbrella issue
listing all issues identified in the analysis.
Possible Implementation
Related material in the current doc:
Following is a top-level outline of the User Guides section of the ducmentation.
Obviously Vitess is a complex product with many moving parts. Nonetheless, this
table of contents (TOC) could be reorganized and reduced to make information
easier to find. Some suggestions follow.
-
- Overview
- Sharding Guidelines
- Unsharded Keyspace
- Sharded Keyspace
- Sequences
- Shared Vindexes and Foreign Keys
- Foreign Keys in Vitess
- Unique Lookup Vindexes
- Non-Unique Lookup Vindexes
- Lookup as Primary Vindex
- Backfill Lookup Vindexes
- Subsharding Vindex
- Advanced VSchema Properties
- Vindex Hints in Vitess
- Pictorial Summary
- VSchema DDL
- Running in Production
- Migration
- SQL Statement Analysis
- Advanced Configuration
- Operational
- Making Schema Changes
-
- Collations and Character sets
- Planning
- Global TopoServer
- vtctld
- Creating a cell
- Keyspaces and Shards
- VTOrc
- VTTablet and MySQL
- Initialize Shard Primary
- Durability Policy
- vtgate
- Backups and Restores
- Reparenting
- Delete a Keyspace
- Add or Delete a Cell
- Monitoring
- Ports
- Troubleshooting
- Exporting data from Vitess
-
- User Management and Authentication
- File based authentication
- LDAP authentication
- Authorization
- Read Query Load Balancing
- VTGate Buffering Scenarios
- Resharding
- Reparenting
- Region Based Sharding
- Creating a LookupVindex
- Comment Directives
- Tracing
- Unmanaged Tablet
- Query Consolidation
- Shard Isolation and Atomicity Model
- Securing Vitess Using TLS
- Troubleshooting Distributed Atomic Transactions
- Integration with Orchestrator
-
- Unmanaged Schema Changes
- Managed, Online Schema Changes
- Online DDL strategies
- ddl_strategy flags
- Table lifecycle
- Applying, auditing, and controlling Online DDL
- Declarative migrations
- Postponed migrations
- Recoverable, failover agnostic migrations
- Revertible migrations
- INSTANT DDL migrations
- Concurrent migration execution
- Validating schema migrations using
VDiff - Advanced usage
Suggested changes:
This is not going to be a quick fix. I'd suggest the following strategies to reorganize the documentation.
This should not be considered a complete list, and contributors should look for opportunities to make instructional information more findable.
Suggestion 1: Eliminate redundant information
Here are some sections that seem (based on their titles, mostly) to contain the same or similar information. It might be possible to consolidate topics with similar information:
The following are links that appear both as top-level TOC entries for User Guides and as sub-headings in the VSchema and Query Serving User Guide. There is probably no need to reference them from two plaaces in the TOC:
- Running in Production
- Migration
- SQL Statement Analysis
- Advanced Configuration
- Operational
- Making Schema Changes
Suggestion 2: Look for similar tasks as sections are renamed
As pages are renamed (see Rename tasks), redundant information should come to light, especially in topic searches. More reduntant pages (especially ones that describe the same task) can then be consolidated and/or eliminated.
Suggestion 3: Move related information closer together
This is especially true of related tasks. Here are some examples of task descriptions that seem to be separated by unrelated information within a user guide: