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.
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:
| Topic |
Main TOC entry |
Section title |
| Keyspace and sharding |
VSchema and Query Serving |
Unsharded Keyspace, Sharded Keyspace |
|
Running in Production |
Keyspaces and Shards |
| Lookup Vindex |
VSchema and Query Serving |
Unique Lookup Vindexes, Non-Unique Lookup Vindexes |
|
Advanced Configuration |
Creating a LookupVindex |
| DDL |
VSchema and Query Serving |
VSchema DDL |
|
Making Schema Changes |
Online DDL strategies, ddl_strategy flags, Applying, auditing, and controlling Online DDL |
| Reparenting |
Running in Production |
Reparenting |
|
Advanced Configuration |
Reparenting |
| Migrations |
Making Schema Changes |
Declarative migrations, Postponed migrations, Recoverable, failover agnostic migrations, Revertible migrations, INSTANT DDL migrations, Concurrent migration execution, Validating schema migrations using VDiff |
|
Migration |
Entire user guide |
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:
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:
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:
These goals are embodied in these strategies:
Reorganize the User Guide:
First, organize by user role, if there are distinct roles.
User roles traditionally are the basis for a "User Guide":
As I understand it, there are basically three user roles in Vitess:
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:
DBA:
Application programmer:
to any tasks that are identical)
(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.
VSchema and Query Serving
Running in Production
Migration
SQL Statement Analysis
Advanced Configuration
Operational
Making Schema Changes
VDiffSuggested 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:
VDiffThe 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:
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: