Remove the FAQ

[dwelsch-esi]

Overview

Remove the FAQ from the documentation site.

A FAQ is only useful as a small repository of commonly needed information. The Vitess FAQ has outgrown this function and is now a separate de facto technical documentation set. Furthermore, it is outside the versioned documentation, which can cause it to go out of date and contain erroneous information.

Move all of the FAQ topics and information into the versioned documentation and remove the FAQ from the table of contents (TOC).

Audience: All

Type: Reference

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:

• FAQ

Suggested changes:

Merge the FAQ 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.

Rename the FAQ-style questions into concise headings when you consolidate the FAQ into the versioned documentation (see Renaming tasks and Reorganizing tasks).

Get rid of the VReplication FAQ
in the reference section and put the information in a troubleshooting section.

[nate-double-u]

This suggestion conflicts with issue #1947.

@rohit-nayak-ps, @dwelsch-esi maybe there's some discussion to be had about the best way forward.

[dwelsch-esi]

This suggestion conflicts with issue #1947.

@rohit-nayak-ps, @dwelsch-esi maybe there's some discussion to be had about the best way forward.

I'm not a big fan of FAQs in general, but it's not my place to say whether you do or don't want one for this project. What I will say is that there is so much information in this FAQ that it essentially constitutes an entire separate shadow documentation set. And worse, it's not versioned, so it's not clear which version(s) any given item in the FAQ refers to. Any of it could be deprecated, obsolete, or inaccurate.

We seem to agree that the FAQ needs to be reorganized. I agree that many short pages would be better than the current format, but the bigger problem to my mind is that there is much redundant information in the FAQ. I'm suggesting that more needs to be done with each item than to just move it to its own file. Any or all of these additional operations would improve the usability of the documentation, in my opinion:

• Evaluate whether it's truly a "frequently asked question" that deserves to be featured in a précis document like a FAQ. If not, eliminate it entirely after making sure it's covered in the versioned documentation.
• Determine whether it's current information. If not, eliminate it from the FAQ.
• In cases where the item is redundant with a current documentation page, delete the FAQ item and instead provide a link to the documentation.