Rewrite tasks

[dwelsch-esi]

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 rewriting.

A reader typically consults the User Guide for task information -- to find out
how to do something. The User Guides should consist primarily of this type of
information. It should be a procedure guide.

There are some Vitess features for which the User Guide gives a description but
does not provide adequate instructions for their use.

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:

• User Guides

Suggested changes:

Here's an outline for a one-page procedure writeup:

• Title ("ABCing XYZ")
  • Context (Describe where the procedure fits in the overall use case)
  • Prerequisites (Hardware and software requirements, dependencies, procedures
    that must be completed first)
  • Procedure ("To ABC an XYZ, do the following.")
    • Step 1 (One CLI command, or action. Don't combine actions.)
    • Step 2 (etc.)
  • Result (Optional - include only if there's something remarkable about the
    outcome.)
  • Next Steps (What procedure or use case typically follows this. If it depends
    on context, explain the options.)

Consider this page from the current guide:
Creating a Backup

This page appears to be well named ("Creating a Backup" is a descriptive task
title) and properly placed (it resides in a logical location in the User Guide).
However, the page itself buries the lead (it doesn't provide the procedure until
far down the page, if at all): There is no actual command line given.
The "how to" procedure should be prominently featured in a section labeled
"Procedure" or something similar.

Further down the page, another backup option, Using mysqlshell, has the same
shortcomings: No actual command is apparent.

Instead, write these pages as step-by-step descriptions of how to perform a
task. Each step should be a concise instruction, with any required instruction
or text illustrated and explained (much of the time, this is a monospace
code/CLI block displaying the command-line instruction to use). This can be an
example, but only if it is obvious how the reader should use the command. Other
times, it means showing the required form of the command, with placeholders for
parameters, and explaining those parameters in the following text.

Write separate procedures, complete with prerequisites, for all variations:
using xtrabackup, using builtin, using vtctl, using mysqlshell, and
partial vs full backup. There might be eight different combinations of backup
types here. They might not all need to be documented, especially if some of
them are rarely used or deprecated. But it's confusing to readers that these
procedures are all intermixed on the same page. Again, the goal is to explain
what the options are and then to write a clear, linear procedure for each
option that the user can follow step by step.

Here's how I'd rewrite one procedure on this page. Notes are in
angle brackets ("<>"):

Creating a Backup

<This is the "Context" information. It can go at the top of the page under
the title without a second-level heading of its own.>

As described in Backup types, you can run a full
backup (the default) or an incremental backup.

Full backups use the backup engine chosen in the tablet's configuration.
Incremental backups always copy MySQL's binary logs, regardless of the
configured backup engine.

The default backup engine is builtin. However, we strongly recommend using
the xtrabackup engine as it is more robust and allows for non-blocking
backups. Restores are always done with whichever engine was used to create
the backup.

This procedure describes how to back up using xtrabackup.

Prerequisites

<It's good practice to number the prerequisites so that the user
doesn't miss one.>

1. Compatible versions of
   xtrabackup
   and
   xbstream
   are present in your $PATH.

2. This backup procedure supports
   MySQL 8.0.

3. To use xtrabackup with Vtbackup, VTTablet or Vtctld, the following
   flags must be set:

   • --backup_engine_implementation=xtrabackup
   • --xtrabackup_user string
     • The user that xtrabackup will use to connect to the database server.
       This user must have the
       necessary privileges.
       • This user must be authorized to connect to mysql locally without
         a password using
         auth_socket.
   • --xtrabackup_stream_mode=xbstream

Procedure

<The page does not describe how to do a backup. Either write the procedure
here, or explain how to configure automatic backups using xtrabackup. If this
is something that MySQL users universally know how to do, at least provide a
reference to the information here.>

Next Steps

<If the procedure described the commands to actually perform the backup,
then the logical thing for "Next Steps" to contain might be a link to the
procedure for setting up periodic automatic backups. >