CNCF Tech Doc Recommendations: Umbrella Issue

[dwelsch-esi]

FEATURE REQUEST: ☂ CNCF Tech Doc Recommendations

[TBD: add sub-issues. Will remove this notice when complete.]

Overview

This is a checklist for the CNCF technical documentation analysis and implementation plan. It should be updated as sub-issues are added, completed, or otherwise modified.

This issue tracks recommended changes resulting from an analysis of the Litmus Chaos documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/analyses/0013-litmuschaos/

The CNCF Litmus Chaos documentation effort is tracked in the CNCF Tech Docs repo:
cncf/techdocs#218

🗞️ Sub-issues

This is a list of issues representing the recommended work on the Litmus Chaos website(s) and technical documentation.

✏️ Single-source documentation

One of the CNCF guidelines for technical documentation is that it have a single source. The Litmus Chaos technical documentation is spread over several repos, which makes it harder to maintain. Obsolete repos should be retired and archived or deleted.

• Single-source documentation #295

✏️ Remove obsolete websites

A Google search turns Litmus Chaos-branded websites that are obsolete and/or unexplained.

Remove or archive Litmus Chaos-branded websites that are obsolete and/or unexplained.

• Remove obsolete websites #296

✏️ Mark a clear "getting started" path

There are at least four "getting started" links on the website. To avoid confusing users, make them all point to the same place, or relabel them so they more accurately reflect the linked content.

• Mark a clear "getting started" path #297

✏️ Remove duplicate install instructions

Rather than duplicating information to different scenarios (basic vs. advanced install) by cutting and pasting, write the duplicated information as a sub-procedure and link to it from the main procedure or include it as a prereq.

• Remove duplicate install instructions #298

✏️ Move contributor info out of intro

Move "How to Contribute" out of the "What is Litmus" page. "What is Litmus" is introductory conceptual material; "How to Contribute" is advanced instructional information for a different audience.

• Move contributor info out of intro #299

✏️ Make ToC agree with content headings

The "Overview" pages in the "Concepts" guide and the User guide both contain synopses of the content within their guides. The table of contents (TOC) on the left displays links to those same sections. To facilitate navigation the information in the overviews should exactly parallel the TOC.

Revise the "Concepts" table of contents (TOC) so that the items appear in the same order as they do on the Overview page. Similarly, make the User Guides TOC agree with the User Guides Overview.

• Make ToC agree with content headings #300

✏️ Move instructional material from Concepts to User Guide

Currently, instructional information is in the User Guide, but some procedures have been embedded in the "Concepts" section. These procedures should be in one place so that users can "shop" in one place for instructions on what they need to do. You can then provide links from the procedure to the relevant Concept, and vice versa.

• Move instructional material from Concepts to User Guide #307

✏️ Integrate the overview material

Move the "Architecture" and "Concepts" section to follow the "Introduction" section. Integrate Concepts and Architecture to reference each other's content for a more complete picture of the system.

• Integrate the overview material #308

✏️ Consolidate community resource information

Combine the "Community" and "More Resources" sections in the Introduction. They are all information resources and there little value in separating them. Consider combining all community resources under a "Community" menu item in the website banner header and removing from the technical documentation altogether.

• Consolidate community resource information #309

✏️ Revise the user guide procedures

Rewrite User Guide stepwise procedures to be more clear and consistent, using a template to ensure they're complete and consistent.

• Revise the User Guide procedures #310

✏️ Remove or reduce screen shots

Replace screen shots with text-based descriptions of the user options to be selected. If If an illustration is still required to point out a GUI element (it usually isn't), crop the screen shot to include the minimum required vertical height and use a drawing program to highlight the element in question.

• Remove or reduce screen shots #311

✏️ Document functionality from blog posts

There are several good articles in the Litmus Chaos blog that expand and
explain Litmus functionality. If any posts explain core functional capabilities,
they should be included in the Litmus technical documentation so they are findable
by users.

• Document functionality from blog posts #312