Update per review comments, including recommendations for FAQ and troubleshooting.

Signed-off-by: Dave Welsch <[email protected]>

Author: dwelsch-esi

analyses/0014-vitess/analysis.md

@@ -145,6 +145,12 @@ works, in both the [Overview](https://vitess.io/docs/21.0/overview/) and
 
 The introduction to the Overview could be more helpful to new users.
 
+There is an extensive FAQ that contains much information of all types, but especially conceptual information. The overview introduction in the FAQ is actually more descriptive and succinct than the one on the main web page:
+
+> Vitess is a database solution for deploying, scaling and managing large clusters of database instances.
+
+The FAQ is outside the versioned documentation.
+
 **Feature complete**: Is the documentation feature complete? (i.e., each product
 feature is documented)?
 
@@ -161,8 +167,9 @@ use Vitess:
 - Setup and use
 - Administration
 
-Except for Installation, all task documentation is in the
-[User Guides](https://vitess.io/docs/21.0/user-guides/).
+Except for Installation, all task documentation is in one of two places:
+- The [User Guides](https://vitess.io/docs/21.0/user-guides/). 
+- An extensive FAQ that contains task instructions. 
 
 Despite being labeled "Task-based guides," the task instructions in the User
 Guide are written from a feature-oriented perspective, which lessens the
@@ -206,7 +213,11 @@ following sections:
 - Advanced > Distributed Atomic Transactions
 - Migration
 
-There is one special-purpose FAQ, for VReplication in the Reference.
+There is a troubleshooting section outside the versioned documentation.
+
+There is a lengthy troubleshooting section in the FAQ.
+
+There is a separate special-purpose FAQ, for VReplication, in the Reference.
 
 There is no glossary.
 
@@ -229,6 +240,11 @@ utilities, and these are documented in the Reference.
 Yes, documentation is versioned and prominently includes the latest Stable and
 Development versions.
 
+However, there are several important sections that are maintained outside the versioned documentation:
+- Troubleshooting
+- FAQ
+- Information about the release procedure
+
 #### New user content
 
 **Getting started entry**: Is “getting started” clearly labeled? (“Getting
@@ -294,6 +310,8 @@ localization/internationalization with regard to site directory structure?
 
 Yes, there are full versions of the documentation in both English and Chinese.
 
+The Chinese versions are reportedly not up to date with the latest software version.
+
 **Localization framework**: Is a localization framework present?
 
 Yes, there seems to be some infrastructure for multiple languages. I'm not sure
@@ -433,9 +451,9 @@ content in at least two ways:
 - Makes the TOC more coherent
 - Gives meaningful results in the site-wide Search
 
-Here are three examples from the [same page]
-(https://vitess.io/docs/21.0/user-guides/configuration-basic/global-topo/) (the
-content of these sections is not considered here):
+Here are three examples from the
+[same page](https://vitess.io/docs/21.0/user-guides/configuration-basic/global-topo/)
+(the content of these sections is not considered here):
 
 - _Choosing a TopoRoot_: A good title. Describes the task ("choosing") and the
   object of the task ("TopoRoot").
@@ -452,15 +470,17 @@ Also on the Global TopoServer page, by the way:
 > The following command line options are required for every Vitess component:
 >
 > ````--topo_implementation=etcd2 --topo_global_server_address=<comma_separated_addresses>
->   --topo_global_root=/vitess/global```
+>   --topo_global_root=/vitess/global
+> ````
 >
 > To avoid repetition we will use <topo_flags> in our examples to signify the above
 >   flags.
-> ````
 
-Remove this. The "<topo_flags>" placeholder does not seem to have been
-implemented. There are no mentions of "<topo_flags"> elsewhere in the
-documentation, and in any case each would have to refer back to this page.
+Remove this. The "<topo_flags>" placeholder does not seem to have been implemented.
+There are no mentions of "<topo_flags"> elsewhere in the documentation, and in any
+case each would have to refer back to this page.
+
+In the FAQ: Rename the questions into concise headings when you consolidate the FAQ into the versioned documentation (see *Reorganize* below).
 
 ###### Rewrite
 
@@ -475,14 +495,13 @@ For example, look at
 
 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 doesn't contain an actual command or set of steps to
-back up a database: There is no actual command line given between
-_Configuration_ and _Common Errors and Resolutions_ The page's author might
-assume that it's implied, but it should be presented explicitly as a step in the
-procedure.
+However, the page itself buries the lede (it doesn't provide the procedure until
+far down the page): There is no actual command line given between
+_Configuration_ and _Common Errors and Resolutions_ The "how to" procedure should
+be prominently featured.
 
 Further down the page, another backup option, _Using mysqlshell_, has the same
-shortcomings: No actual command is presented.
+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
@@ -584,18 +603,24 @@ _Application programmer_:
   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.
+(Again, these are my understanding of the Vitess user roles. Adjust the details if
+they're different.)
+
+Get rid of the FAQ. This FAQ has apparently grown from a repository for common questions into a separate de facto technical documentation set. Move all of the FAQ topics and information into the versioned documentation. 
+
+Merge information with existing sections and/or move FAQ topics to the documentation intact, as appropriate. For example, much of the FAQ amounts to a good conceptual overview of the product; it should be part of the conceptual overview. In its current form it is unversioned and hard to find.
+
 
 ###### Troubleshooting
 
-Consolidate all troubleshooting information into a Troubleshooting Guide. Or,
-create one troubleshooting guide per user guide/user role. In either case,
-create an escalation path for any problems with a task (the escalation path
-might be: _troubleshooting procedure > Slack Channel > project Issue_). Get rid
-of the
-[VReplication FAQ](https://vitess.io/docs/21.0/reference/vreplication/faq/) in
-the reference section and put the information in a troubleshooting section.
+Consolidate all troubleshooting information into a Troubleshooting Guide. Or, create
+one troubleshooting guide per user guide/user role. In either case, create an escalation
+path for any problems with a task (the escalation path might be:
+*troubleshooting procedure > Slack Channel > project Issue*). Get rid of the
+[VReplication FAQ](https://vitess.io/docs/21.0/reference/vreplication/faq/)
+in the reference section and put the information in a troubleshooting section.
+
+Locate the troubleshooting guide or guides within the versioned technical documentation. Changes to the product affect troubleshooting procedures as well as other types of information, and the documentation structure should reflect that.
 
 ###### Glossary
 
@@ -896,7 +921,7 @@ gracefully when magnified in the browser.
 **Case studies**: Are there case studies available for the project and are they
 documented on the website?
 
-No, I did not see any case studies. Some of them many videos might contain case
+No, I did not see any case studies. Some of the many videos might contain case
 studies, though.
 
 **Testimonials**: Are there user testimonials available?