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