cncf
/
techdocs
mirror of https://github.com/cncf/techdocs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #275 from dwelsch-esi/litmuschaos-analysis 

LitmusChaos TechDocs Analysis

Signed-off-by: Nate W <natew@cncf.io>
This commit is contained in:
Nate W 2024-12-06 12:10:58 -08:00 committed by GitHub
parent 8dc4600f73 b9c2c39006
commit a4f745b293
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 1591 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

721
analyses/0013-litmuschaos/litmuschaos-analysis.md Normal file
View File

@ -0,0 +1,721 @@
---
title: LitmusChaos Documentation Analysis
tags: LitmusChaos
created: 2024-08-02
modified: 2024-10-09
author: Dave Welsch (@dwelsch-esi)
---
<!-- markdownlint-enable line-length -->
<!-- cSpell:ignore Docusaurus rfc OSes pastable impl servicedesk md -->
<!-- markdownlint-disable no-duplicate-heading -->
## Introduction
This document analyzes the effectiveness and completeness of the
[LitmusChaos][project-website] open source software (OSS) project's
documentation and website. It is funded by the CNCF Foundation as part of its
overall effort to incubate, grow, and graduate open source cloud native software
projects.
According to CNCF best practices guidelines, effective documentation is a
prerequisite for program graduation. The documentation analysis is the first
step of a CNCF process aimed at assisting projects with their documentation
efforts.
### Purpose
This document was written to analyze the current state of LitmusChaos
documentation. It aims to provide project leaders with an informed understanding
of potential problems in current project documentation. A second
[implementation] document outlines an actionable plan for improvement. A third
document is an [issues list] of issues to be added to the project documentation repository.
These issues can be taken up by contributors to improve the documentation.
This document:
- Analyzes the current LitmusChaos technical documentation and website
- Compares existing documentation against the CNCF’s standards
- Recommends a program of key improvements with the largest return on investment
### Scope of analysis
The documentation discussed here includes the entire contents of the website,
the technical documentation, and documentation for contributors and users on the
LitmusChaos GitHub repository.
The LitmusChaos website is generated using a Next/React framework. It is stored
on the LitmusChaos GitHub repo.
The documentation page is written in Markdown and is compiled using the
Docusaurus static site generator. The site's code is stored on the LitmusChaos
GitHub repo.
#### In scope
- Website: <https://litmuschaos.io/>
- Website repo: <https://github.com/litmuschaos/litmus-website-2>
- Documentation repo: <https://github.com/litmuschaos/litmus-docs/>
- Main project repo (for governance and contributor docs):
<https://github.com/litmuschaos/litmus>
#### Out of scope
- Other LitmusChaos repos: <https://github.com/litmuschaos/>\*
- Litmus Software (a completely unrelated company and product based in
Massachusetts): https://litmus.com/*
### How this document is organized
This document is divided into three sections that represent three major areas of
concern:
- **Project documentation:** concerns documentation for users of the LitmusChaos
software, aimed at people who intend to use the project software
- **Contributor documentation:** concerns documentation for new and existing
contributors to the LitmusChaos OSS project
- **Website:** concerns the mechanics of publishing the documentation, and
includes branding, website structure, and maintainability
Each section begins with summary ratings based on a rubric with appropriate
[criteria] for the section, then proceeds to:
- **Comments**: observations about the existing documentation, with a focus on
how it does or does not help LitmusChaos users achieve their goals.
- **Recommendations**: suggested changes that would improve the effectiveness of
the documentation.
The accompanying [implementation] document breaks the recommendations down into
concrete actions that can be implemented by project contributors. Its focus is
on drilling down to specific, achievable work that can be completed in
constrained blocks of time. Ultimately, the implementation items are decomposed
into a series of [issues] and entered as
[GitHub issues](https://github.com/litmuschaos/litmus-docs/issues).
### How to use this document
Readers interested only in actionable improvements should skip this document and
read the **[implementation] plan** and **[issues] list**.
Readers interested in the current state of the documentation and the reasoning
behind the recommendations should read the section of this document pertaining
to their area of concern:
- [Project documentation](#project-documentation)
- [Contributor documentation](#contributor-documentation)
- [Website and documentation infrastructure](#website-and-infrastructure)
Examples of CNCF documentation that demonstrate the analysis criteria are linked
from the [criteria] specification.
#### Recommendations, requirements, and best practices
This analysis measures documentation against CNCF project maturity standards,
and suggests possible improvements. In most cases there is more than one way to
do things. Few recommendations here are meant to be prescriptive. Rather, the
recommended implementations represent the reviewers' experience with how to
apply documentation best practices. In other words, borrowing terminology from
the lexicon of [RFCs][rfc-spec], the changes described here should be understood
as "recommended" or "should" at the strongest, and "optional" or "may" in many
cases. Any "must" or "required" actions are clearly denoted as such, and pertain
to legal requirements such as copyright and licensing issues.
## Project documentation
LitmusChaos is an **incubating** project of CNCF, applying to be a **graduated**
project. This means that the project should have [_very high_][criteria]
standards for documentation.
| Criterion | |
| -------------------------- | -------------------- |
| Information architecture | 2. Needs improvement |
| New user content | 2. Needs improvement |
| Content maintainability | 2. Needs improvement |
| Content creation processes | 2. Needs improvement |
| Inclusive language | 2. Needs improvement |
### Comments
The following sections contain brief assessments of each element of the Project
Documentation rubric.
Organization of the [doc page](https://docs.litmuschaos.io/) at the top level is
unconventional. The Documentation tab in the banner menu has several graphically
displayed options. The main one leads to a documentation main page that has
tiled options organized in groups:
- Explore using Litmus
- Litmus for Advanced Users
- More Resources
There is also a Versions drop-down on the doc main page. Selecting the most
recent version (3.91) brings up the "What is Litmus" page (the first page in the
first ToC heading).
#### Information architecture
There is high level, conceptual “About” content. This content is split between
at least two sections, "Introduction" and "Concepts".
The main documentation site seems feature-complete. However, the documentation
resides on several websites. The tutorials have their own site
The documentation for the [API][api-site] is on its own website and is
maintained from the main project repository. The API documentation is
incomplete, containing very sparse semantic information about the API endpoints,
objects, and actions.
There are step-by-step instructions for most important functionality, including
installation, configuration, and running a "first-time" experiment.
- Formatting and organization of the instructions is inconsistent.
- Some minor functionality does not have complete step-by-step instructions. For
example, a link in the instructions to connect an external delegate in
_Schedule a chaos scenario_
point to the `litmusctl` reference. While relevant, this is not the same as
explicit instructions for connecting to a delegate.
<!-- markdownlint-enable line-length -->
The "happy path" seems well documented, but disorganized. This includes a basic
Getting Started workflow ("Installation" and "Run Your First Chaos Scenario")
and components of setting up and using a test program.
The Overview to the User Guide section provides minimal guidance. Instead, it
presents a bucket of tasks under the apparent assumption that the user will know
what to do with them. The individual tasks are atomic and well documented.
There are escalation paths in the documentation, including a FAQ, a
Troubleshooting section, and a link to the
[Issues](https://github.com/litmuschaos/litmus/issues) section in the project
main GitHub repo. There is also a Community section in the table of contents
that describes the Slack channel, community meetings, events, and so on.
The content seems up to date. There is a version selection drop-down that
contains the latest release of the product.
#### New user content
New users will be confused as to where to start. There are at least four
"getting started" links on the website.
- There is a "Get Started" button in the product website menu that links to the
GitHub repo.
- There is a clearly labeled "Getting Started" button on the main documentation
page that clicks through to the "What is Litmus?" introduction page.
- There is also a "Getting Started" heading in the table of contents. This
contains "Resources" (first) and "Installation" (second).
- There is a completely separate tutorials website (based on a separate GitHub
repo) that contains a "getting started" tutorial.
Installation is documented in both self-hosted and hosted (beta) forms.
Self-hosted installation is further divided into Helm- and YAML-based (kubectl)
processes. The last step of the kubectl install process has two options, basic
and advanced. The advanced option takes the user to yet another install page,
"ChaosCenter Advanced Installation".
The advanced install page is a duplicate of the main install page, with
duplicate Helm install instructions and verification procedure; the only
difference is a few lines in the kubectl install procedure. The duplication is
confusing and seems unnecessary.
Installation of the CLI (litmusctl) is documented for Mac and Windows. No
explicit mention is made of what OS the standalone server runs on, or if
litmusctl can be run on Linux.
The various installation and setup pages each have a "Learn more" section at the
end containing several links to next steps. The various paths available are not
explained and overall do not constitute a getting-started workflow.
Installation CLI commands and config file sample contents are provided where
appropriate and are presented in copyable text window widgets. Apparently these
are inserted by `embedmd`.
#### Content maintainability & site mechanics
The documentation is searchable. However, search does not seem to be limited to
the current version. For example, searching on "Advanced Installation" brings up
results for the current (3.91) version, the previous (3.90) version, and the
upcoming (3.92) version.
Documentation is entirely in English, and in fact there is an
[open issue](https://github.com/litmuschaos/litmus-docs/issues/271) to add
support for other languages.
Previous versions of the documentation are archived and are available on the
website via a pull-down menu. There is an automatic versioning command
documented in the documentation repo.
#### Content creation processes
The documentation build process is documented in README files on the doc GitHub
repo; it consists of brief descriptions of the commands needed to build the
documentation locally. There don't seem to be deployment instructions.
Instructions for contributing doc changes are in the CONTRIBUTING.md file in the
docs repo.
There is nothing in the main release process about documentation. There is a
wikiin the main project repo. One of the things it contains is a list of SIGs
and one of the SIGs is documentation. However, the SIG document has not been
edited since early 2021.
There are documentation maintainers and reviewers listed in the main repo
MAINTAINERS.md file.
#### Inclusive language
There are a few examples of non-recommended words as documented by the
[Inclusive Naming Initiative](https://inclusivenaming.org) website. Some of
these cannot be summarily changed because they appear in pathnames, commands,
and as parameter names.
The project also uses terms like "simple", "easy", and so on in what could be
considered ableist context in a few instances.
### Recommendations
#### Information architecture
Consolidate the conceptual information into a single technical overview.
Create and maintain a site map that describes the components of the
documentation set. Consolidate the documentation so that, to the extent
possible, it is maintained in a single repo.
Add semantic information and examples to the API reference. Current API
documentation is mostly skeletal, containing no guidance on how to use the API
elements.
Write tasks and procedures as step-by-step instructions. Ensure that tasks are
complete. For complex procedures, it's OK to link to sub-procedures or (usually
better) put preliminary tasks in the Prerequisites section.
Ensure that installation, setup, and verification have a clear, linked path for
each user role. See [New user content](#New-user-content) below.
Organize the User Guide by task. Some of the tasks will align with the current
function-based organization, but some will not. If necessary, split it into two
or more guides, one for each distinct user role. Describe the use case for each
user role at the top of the guide.
#### New user content
Make all "Getting Started" links point to the same place. This should be a
landing page that describes the main user roles or user scenarios and links to a
separate getting-started workflow for each one. For example, self-hosted and
hosted installs are probably appropriate for developer and admin user roles,
respectively. Explain the usage scenario at the top of each procedure.
Rather than duplicating information in different scenarios (basic vs. advanced
install, for example), write single sub-procedures and link to them from the
main procedure or include them as prereqs.
Explicitly call out the operating system for every install procedure.
Rename "Learn more" at the end of procedures and tasks to "Next steps". Explain
who would want to do each item and why in a short paragraph.
#### Content maintainability & site mechanics
Limit on-site search to the current version of the documentation.
#### Content creation processes
Add documentation as a step in the project release process. Link to the
CONTRIBUTING.md doc in the docs repo.
Update the wiki in the main project repo to indicate that the documentation SIG
is no longer active, and provide a link so that users can find monthly meetings
or whatever the closest replacement is.
Ensure that the documentation maintainers listed in the MAINTAINERS.md file in
the main project repo are up to date.
#### Inclusive language
Audit the documentation and replace instances of non-recommended words from the
[Inclusive Naming Initiative](https://inclusivenaming.org) website, especially
tier 1 and tier 2 words, where possible. Similarly, audit the site for words and
phrases like "simple", "easy", and "just have to ..." where they imply actions
that might be difficult for disabled users.
## Contributor documentation
LitmusChaos is an **incubating** project of CNCF, applying to be a **graduated**
project. This means that the project should have [_very high_][criteria]
standards for documentation.
| Criterion | |
| ----------------------------------------- | ----------------------------- |
| Communication methods documented | 4. Meets or exceeds standards |
| Beginner friendly issue backlog | 2. Needs improvement |
| “New contributor” getting started content | 3. Meets standards |
| Project governance documentation | 3. Meets standards |
### Comments
The following sections contain brief assessments of each element of the
Contributor Documentation rubric.
#### Communication methods documented
There is a link to a
[community resources page](https://litmuschaos.io/community) in the website
banner menu. There are links to the Slack channel in the banner menu and the
footer of the documentation pages.
Likewise, there are links to the GitHub repositories, especially the main
project repo.
Monthly community meetings are documented in the main GitHub repo README.md
file. Interested parties can fill out a form to be invited to the meeting.
There is a Meetup group for Litmus Chaos, apparently based in Bangalore, India.
Besides local events, there are virtual events scheduled in the group.
#### Beginner friendly issue backlog
Documentation issues seem to be triaged by maintainers in a timely manner.
There is a "good first issue" label for documentation issues, though it has been
applied to only one currently open issue.
Quality of documentation issues is inconsistent. Some are thoroughly described,
some are skeletal.
There does not seem to be a process for retiring stale issues. Of the 21 issues
in the doc repo at the time of this writing, 16 are over two years old.
#### New contributor getting started content
There is a clearly marked Community link on the documentation website.
The CONTRIBUTING.md file in the documentation repo explains how to start
contributing documentation and invites newcomers to community meetings and the
SIG group. This information seems out of date, however, and the SIG group seems
to have gone dormant.
New contributors probably end up going to the Litmus Slack channel and asking
for help getting started.
#### Project governance documentation
Project governance is documented in the GOVERNANCE.md document on the main
project GitHub repository. The document includes maintainer responsibilities and
reference to the project's Code of Conduct. The document references sub-project
repositories.
The documentation repository does not have its own explicit governance document.
Its CONTRIBUTING.md file does not address governance.
### Recommendations
#### Communication methods documented
No recommendations.
#### Beginner friendly issue backlog
Make sure documentation issues are fully described. Flag and retire stale
issues.
#### New contributor getting started content
Update the CONTRIBUTING.md file to reflect current community practices.
#### Project governance documentation
No recommendations.
## Website and infrastructure
LitmusChaos is an **incubating** project of CNCF, applying to be a **graduated**
project. This means that the project should have [_very high_][criteria]
standards for documentation.
| Criterion | |
| ------------------------------------------- | ----------------------------- |
| Single-source for all files | 2. Needs improvement |
| Meets min website req. (for maturity level) | 2. Needs improvement |
| Usability, accessibility, and design | 2. Needs improvement |
| Branding and design | 2. Needs improvement |
| Case studies/social proof | 4. Meets or exceeds standards |
| SEO, Analytics, and site-local search | 2. Needs improvement |
| Maintenance planning | 2. Needs improvement |
| A11y plan & implementation | 1. Not present |
| Mobile-first plan & impl. | 4. Meets or exceeds standards |
| HTTPS access & HTTP redirect | 4. Meets or exceeds standards |
| Google Analytics 4 for production only | 1. Not present |
| Indexing allowed for production server only | 1. Not present |
| Intra-site / local search | 3. Meets standards |
| Account custodians are documented | 2. Needs improvement |
### Comments
The Litmus web presence seems uncoordinated and sporadically maintained.
The following sections contain brief assessments of each element of the Website
and documentation infrastructure rubric.
#### Single-source requirement
Litmus has separate websites for its documentation and for its project website.
The project website has been replaced:
The [new project repo](https://github.com/litmuschaos/litmus-website-2) seems to
be currently maintained and was last touched in May of 2024.
An obsolete website named "website-litmuschaos: is archived at the same GitHub
URL and was last updated three years ago. The archived repo is listed on the
project page. Aside from a "Public archive" badge in the repo directory, there
is no indication that the old website repo is inactive, nor is there a link in
the archive to the current repo.
There is a dedicated repository for the LitmusChaos documentation. However, the
following documentation is maintained separately, in different locations:
- The **tutorials** do not seem to have been provided beyond release 2. The menu
item for Tutorials is missing from v3.0 and later. The tutorial directory and
repository are separate from those for the main documentation site.
- The **API** for the control center is separate from the main documentation and
seems to be served from GitHub.
The API seems to be documented from the main code repo. There is no hint that
this is the API documentation (unless you're aware that the `mkdocs` directory
is for the API). There does not seem to be a documented strategy for updating
the API or linking the API to the documentation website.
#### Minimal website requirements
Listed here are the minimal website requirements for projects at graduated
[maturity level][maturity-level].
<!-- markdownlint-disable line-length -->
| Criterion | Graduated Requirement | Met? |
| ----------------------------- | ----------------------------------------- | ---- |
| [Website guidelines] | All guidelines satisfied | No |
| **Docs analysis** (this) | All follow-up actions addressed | No |
| **Project doc**: stakeholders | All stakeholder need identified | No |
| **Project doc**: hosting | Hosted directly | TODO |
| **Project doc**: user docs | Fully addresses needs of key stakeholders | No |
[maturity-level]:
https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations
<!-- markdownlint-enable line-length -->
#### Usability, accessibility and devices
**Mobile**:
The website is very usable from mobile.
- Pages are readable
- Menus and site search work
- The table of contents is available in a hamburger menu
A mobile-first design probably does not make sense for this project, but the
mobile version works very well.
**Accessibility**:
Lavender and light blue text might not have enough contrast for vision-impaired
readers.
Keyboard control of website features is awkward and does not work as labeled.
For example, cmd-K does not enable search, at least in MacOS.
There is no text-to-speech option available on the site.
#### Branding and design
Branding seems inconsistent.
There is a recognizable logo and color scheme for most of the sites. However,
sites that are built from other repos (the API, the experiment library) have
different color schemes and font choices. For example, the font used in the logo
is different between the project website and the documentation website.
Page design uses different layouts on different pages. The documentation layout
is a single column, with graphics in-line, which is appropriate. The project
landing page, the API page, and the tutorial page all use different layouts.
The brand's base font is a legible sans-serif font. The tutorial site landing
page uses similar fonts but the tutorials themselves have a completely different
look and feel, with a serif font and an outdated left-justified single frame
presentation.
Several of the project pages, including the blog and the ChaosHub page, use a
tiled layout. However, the tiles are of very different sizes so the feel of
these pages is not consistent.
Many of the graphical elements on the project landing page seem like they should
link to further information, but don't. For example, the list of features
contains a tile with a link to "View more features", but the specific feature
tiles on the page ("ChaosHub", "Litmus Experiments") are not clickable.
#### Case studies/social proof
There is a page of case studies available from the Community drop-down in the
main page banner menu. It contains links to six case studies.
There is a carousel of testimonials, with links to four case studies, on the
project landing page; however, it is far down the page.
There is a blog for Litmus, available from the banner menu on the project
website. The blog does not seem active. The last post is from about a year ago,
and there is at least one broken link.
An announcement features prominently in the Community drop-down from the banner
menu. The announcement is about Litmus becoming a CNCF incubator project and
dates from January of 2022.
There is a carousel of community links far down the project landing page. Two of
the links are to videos. The main project contains a list of videos in the
README.md file.
There is a Litmus Chaos channel on YouTube featuring how-to videos and
recordings of community meetings. Only a few community meetings are posted;
either the monthly meeting schedule is not being kept or the recordings are not
being posted regularly.
There is a logo wall of 70 organizations that use Litmus on the project landing
page. None of the logos link to anything.
#### SEO, Analytics and site-local search
- Analytics:
- Analytics is not enabled for the site.
- Is site indexing supported for the production server, while disabled for
website previews and builds for non-default branches?
- Local intra-site search is not available from the website, though it is
available on the documentation subsite.
- The current custodian(s) of the following accounts are not yet clearly
documented: analytics, Google Search Console, site-search (such as Google CSE
or Algolia)
#### Maintenance planning
As far as I can tell, here is the website tooling for each of the various Litmus
websites:
<!-- markdownlint-disable line-length -->
| Site | Repository | Tool or Stack |
|-----------| -------------------------------------------------------- | ------------------------ |
| [Project website](https://litmuschaos.io/) | https://github.com/litmuschaos/litmus-website-2 | React/Next/Tailwind/SCSS |
| [Documentation website](https://docs.litmuschaos.io/) | https://github.com/litmuschaos/litmus-docs/ | Docusaurus/Netlify |
| Tutorials | https://github.com/litmuschaos/tutorials | Google Codelab? |
| [APIs][api-site] | https://github.com/litmuschaos/litmus/tree/master/mkdocs | MkDocs |
<!-- markdownlint-enable line-length -->
Instructions for maintaining the website are given in the CONTRIBUTORS.md file
in the doc repo. There seems to be an active mentorship program for the project,
but not necessarily for documentation.
The site build time is probably reasonable, though maintaining separate builds
for the site, docs, tutorials, and the API adds complexity and takes time.
Site maintainers presumably have adequate permissions to clone the doc repo(s)
and submit PRs.
#### Other
All the Litmus Chaos sites use HTTPS. All the Litmus sites automatically
redirect HTTP to HTTPS.
### Recommendations
#### Single-source requirement
Combine all the website pages into a single repo. Ideally, this includes:
- The project website
- The documentation
- The API
- Tutorials
Use a single website technology stack for the entire site.
If it's not possible to consolidate these sites immediately, at least document
the satellite repos and provide links to them in the README.md file for the
project website.
#### Minimal website requirements
Update the website to meet the following [Website guidelines]:
- Update notice on the project page to "We are a CNCF Graduated Project" when
that happens.
- Mention CNCF on the documentation pages, not just the project landing page.
- Include the trademark usage info and link on all pages, not just the project
landing page.
Describe the project stakeholders (user roles) and direct website users to
documentation specific to each role. It might be that there is only one primary
user role for Litmus, a DevOps or test engineer. If this is so, spell out the
use cases for this user and make sure to direct readers to tasks for each use
case.
#### Usability, accessibility and devices
Consider revising the site look and feel to include more contrasting color
choices.
Either fix the command-K search functionality or remove the command-K icon from
the search input.
#### Branding and design
Audit the look and feel so that the logo, colors, fonts, and layouts are
consistent throughout the project, community, blog, and doc websites.
Consider adding links from the graphic elements on the project landing page.
#### Case studies/social proof
Fix the broken link on the blog page.
Update or remove the CNCF announcement in the banner menu Community drop-down.
#### SEO, Analytics and site-local search
No analytics setup. Recommend adding LitmusChaos to the CNCF Google Analytics
account.
Search is available for documentation, but it doesn't appear available for other
parts of the website (like the blog or community pages.)
#### Maintenance planning
Build all websites from the same repo using the same tech stack. See
[Single-source requirement](#single-source-requirement).
#### Other
No recommendations.
#### References and notes
##### Rating values
The numeric rating values used in this document are as follows:
1. Not present
2. Needs improvement
3. Meets standards
4. Meets or exceeds standards
5. Exemplary
[api-site]: https://litmuschaos.github.io/litmus/graphql/v2.0.0/api.html
[criteria]: ../../docs/analysis/criteria.md
[implementation]: ./litmuschaos-implementation.md
[issues]: ./litmuschaos-implementation.md
[issues list]: ./litmuschaos-implementation.md
[project-website]: https://litmuschaos.io/
[rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119
[website guidelines]: ../../docs/website-guidelines-checklist.md

254
analyses/0013-litmuschaos/litmuschaos-implementation.md Normal file
View File

@ -0,0 +1,254 @@
---
title: Implementing LitmusChaos Doc Improvements
tags: LitmusChaos
created: 2024-10-24
author: Dave Welsch (@dwelsch-esi)
---
<!-- markdownlint-disable no-duplicate-heading -->
## Introduction
This document provides actionable suggestions for improving the LitmusChaos
technical documentation.
For an analysis and general discussion of recommendations on LitmusChaos
technical documentation, see [the analysis](./litmuschaos-analysis.md).
### Recommendations, requirements, and best practices
This analysis measures documentation against CNCF project maturity standards and
suggests possible improvements. In most cases there is more than one way to do
things. Few recommendations here are meant to be prescriptive. Rather,
recommendations are based on documentation best practices as understood by the
reviewers. The recommended implementations represent the reviewers' experience
with how to apply those best practices. In other words, borrowing terminology
from the lexicon of [RFCs][rfc-keywords], the changes described here should be
understood as "recommended" or "should" at the strongest, and "optional" or
"may" in many cases. Any "must" or "required" actions are clearly denoted as
such, and pertain to legal requirements such as copyright and licensing issues.
## Implementation
### Overview
The top-level documentation recommendations for this project are:
[Consolidate the documentation](#consolidate-documentation-websites)
- Combine the website and all documentation in one repository
- Create a site map
- If there are elements that cannot be moved to the single repository, link to
their locations in the website repository README file
- Use one website stack for the entire documentation site
- Remove, archive, or annotate obsolete repos and documents so that potential
contributors don't waste time with them
- Update or deprecate the tutorials
- Retire the obsolete website and documentation repos
- Remove notifications of past events
[Organize the documentation](#organize-the-documentation)
- Combine similar information so that the user doesn't have to search for it in
more than one place.
- Write an end-to-end Getting Started workflow.
- Clearly identify a single Getting Started landing page from which the Getting
Started workflows begins
- Link all "Getting Started" buttons to the Getting Started landing page
- Combine the conceptual information into one section
[Clarify writing](#clarify-the-writing)
- Review format and writing of step-by-step instructions
- Break tasks down into sub-tasks if necessary
- Removed copy-pasted instructions and make them sub-tasks, especially in the
installation sections
- Be clear about what OSes the installs are for
[Other improvements](#other-improvements)
- Fix search so that it brings up results only from the current version
- Add documentation to the contributing process in the main repo
- Remove non-inclusive language where possible
- Update the contributor information to clearly point to instructions and
resources.
- Update all the website pages to have the same look and feel -- use the same
fonts, colors, and layouts
- Consider modifying the color scheme for greater contrast
- Fix broken links
- Provide a template or instructions for writing issues so that incomplete
issues are not accepted
### Consolidate documentation websites
Consolidate the documentation so that it is maintained in a single repo.
Ideally, this includes:
- The project website
- The documentation
- The APIs
- Tutorials
Archive and retire repos that are no longer in use so that they don't appear in
web searches. If it's necessary to generate or host documentation separately
(for example, maybe the API documentation because it's generated using OpenAPI),
then provide a roadmap on the documentation landing page that describes and
links to each part.
Use a single website technology stack for the entire site.
If it's not possible to consolidate these sites immediately, at least document
the satellite repos and provide links to them in the README.md file for the
project website.
### Organize the documentation
Reorganize the documentation so that like information appears with like.
- Combine the conceptual information (from "Introduction" and "Concepts") into a
single technical overview. Alternatively, use the "Concepts" as the basis for
a glossary.
- The existing Glossary is an explanation of the types of chaos resources and
the changes in terminology from Litmus Chaos 2 to 3.0. These changes are
already documented in "Features" in the Introduction. They should be
incorporated into the glossary as well, by making notes in the individual
terms' entries.
- Move the "How to Contribute" section out of "What is Litmus" -- "What is
Litmus" is introductory material and it makes no sense to look for contributor
information there. Put "How to Contribute" at the end of the Developer Guide
or remove it from the doc entirely and put it in the code repo.
Fix the "Teaming" link in Concepts -> Overview in the table of contents. It
clicks through to "Resilience Probes" rather than the "Teaming" section.
Fix the broken link on the blog page.
There are at least four "getting started" links on the website.
<!-- markdownlint-disable line-length -->
| Link | Location | Refers to |
| --------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| _Get Started_ button | [Product landing page](https://litmuschaos.io/) | [GitHub repo]() |
| _Get Started_ button | [Doc landing page](https://docs.litmuschaos.io/) | [ChaosCenter installation](https://docs.litmuschaos.io/docs/getting-started/installation) |
| _Getting Started_ link | [Doc landing page](https://docs.litmuschaos.io/) | [What is Litmus?](https://docs.litmuschaos.io/docs/introduction/what-is-litmus) |
| _Getting Started_ TOC entry | [Doc page](https://docs.litmuschaos.io/docs/) left-side menu | [ChaosCenter installation](https://docs.litmuschaos.io/docs/getting-started/installation) |
| _Getting started_ tutorial | Tutorial site | [Getting started tutorial](https://litmuschaos.github.io/tutorials/tutorial-getting-started/index.html#0) |
<!-- markdownlint-enable line-length -->
Make all "Getting Started" links point to the same place. This should be a
landing page that describes the main user roles or user scenarios and links to a
separate getting-started workflow for each one. For example, self-hosted and
hosted installs are probably appropriate for developer and admin user roles,
respectively. Explain the usage scenario at the top of each procedure.
Here's an example outline for deciding how to install. Each bullet item should
be its own page.
- **Installation**: Choose hosted Litmus service or install to local Kubernetes
cluster
- **Hosted**: Use a hosting service such as
[Harness](https://app.harness.io/auth/#/signin).
- **Local** (self-hosted): Use _Helm_ or `kubectl`
- **Helm**: One-page install procedure.
- **kubectl** (with a YAML spec file) Prereq: install MongoDB
- **Basic installation**: One-page install procedure.
- **Advanced installation**: One-page install procedure.
- **Verify your installation**: One-page procedure. Next steps: Access the
ChaosCenter.
Ensure that installation, setup, and verification have a clear workflow. If
these instructions vary significantly between user roles, write a separate
workflow for each user role. See [New user content](#new-user-content) below.
Rename "Learn more" at the end of procedures and tasks to "Next steps". Explain
who would want to do each item and why in a short paragraph.
Limit on-site search to the current version of the documentation.
### Clarify the writing
Update the API reference to include semantic information and examples. Consider
writing an introduction to the API reference that explains the underlying model,
or provide a link to the Architecture section from the API introduction.
The User Guides contain stepwise procedures, but these could be written more
clearly. Procedures are the heart of user documentation, so we discuss them in
detail here. Some guidelines for writing procedures:
- Ensure that tasks are complete. For complex procedures, it's OK to link to
sub-procedures or (usually better) put preliminary tasks in the Prerequisites
section.
- Be consistent when writing similar sections, especially procedures. Using a
template can make this easier.
- Use gerunds ("-ing" verbs) to title procure pages; for example "Scheduling a
chaos experiment" rather than "Schedule a chaos experiment".
- Rather than duplicating information in different scenarios (basic vs. advanced
install, for example), write single sub-procedures and link to them from the
main procedure or include them as prereqs.
- Explicitly state which operating systems and platform the installation is for.
This can be done in the Prereqs section.
- In all cases, use consistent naming for the sections as an aid to navigation.
For example, the current documentation uses "Prerequisites" and "Before you
begin" for the same information.
- Similarly, retitle "Learn More" as "Next Steps", and write explanations for
each option
- A basic outline for a procedure should include:
1. Introduction - provide context for the task.
2. Prerequisites: System requirements, operating systems, network, databases -
anything that needs to be in place before the installation.
3. Step by step instructions: Number the steps. Provide only one action per
step. An action is a CLI command, GUI action -- anything that must be done
before moving on to the next step. For CLI commands, file contents, and so
on, provide copyable text. Don't combine steps, especially when they must
be done in sequence.
4. Results (optional; not needed if the results are obvious): What happens
when the procedure is successful. Can include an instruction for how to
verify results.
5. Next steps: Links to one or more procedures that the user might reasonably
want to do next. This might be a link to the next step in a larger
procedure, or to options that are available now that the task is finished.
Expand the glossary. Make the glossary purely a reference that defines terms.
### Other improvements
Add documentation as a step in the project release process. Link to the
CONTRIBUTING.md doc in the docs repo.
Update the wiki in the main project repo to indicate that the documentation SIG
is no longer active, and provide a link so that users can find monthly meetings
or whatever the closest replacement is.
Ensure that the documentation maintainers listed in the MAINTAINERS.md file in
the main project repo are up to date.
Audit the documentation and replace instances of non-recommended words from the
[Inclusive Naming Initiative](https://inclusivenaming.org) website, especially
tier 1 and tier 2 words, where possible. Similarly, audit the site for words and
phrases like "simple", "easy", and "just have to ..." where they imply actions
that might be difficult for disabled users.
Clean up the backlog of documentation issues.
Make sure documentation issues have complete descriptions.
- Update the CONTRIBUTING.md file to reflect current community practices.
- Update the website to meet the following [Website guidelines]:
- Put the CNCF branding label in the site's footer.
- Similarly for the trademark usage info and link on all pages.
- Update notice on the project page to "We are a CNCF Graduated Project" when
that happens.
Either fix the command-K search functionality or remove the command-K icon from
the search input.
Audit the look and feel so that the logo, colors, fonts, and layouts are
consistent throughout the project, community, blog, and doc websites. Consider
revising the site look and feel to include more contrasting color choices.
Consider adding links from the graphic elements on the project landing page.
Update or remove the CNCF announcement in the banner menu Community drop-down.
Implement analytics.

616
analyses/0013-litmuschaos/litmuschaos-issues.md Normal file
View File

@ -0,0 +1,616 @@
---
title: Litmus Chaos Issue
tags: Litmus Chaos
---
This document contains a list of issues to be entered in the Litmus Chaos
documentation repo more or less verbatim.
## Issue: Single-source documentation
### Overview
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. Some of the repos are obsolete; these should
be retired and archived or deleted.
Consolidate the documentation so that it is maintained in a single repo. If this
is not practical for some of the repos (it might be difficult to move the API
doc, for example, if it is generated from code), then document their location in
the README file in the main documentation repo. Make it clear which repos are
active and which are retired.
Use a single website technology stack for the entire site if possible.
Audience:
This issue concerns all users of the documentation.
Type:
This is an infrastructure issue that encompasses all the information on several
websites.
### Context
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> under
`0013-litmuschaos`.
### Possible Implementation
The following repos are affected:
| Repo URL | Description | Recommendation |
| -------------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------- |
| https://github.com/litmuschaos/litmus-website-2 | The project website repo | Combine with the doc repo |
| https://github.com/litmuschaos/litmus-docs | Documentation repo | Combine with website repo |
| https://github.com/litmuschaos/v1-litmus-docs | Another documentation repo, for docs before 2.0 | Move toward retiring and archiving. |
| https://github.com/litmuschaos/website-litmuschaos | Previous website repo | Already archived. Include new repo URL in archive banner. |
| https://github.com/litmuschaos/tutorials | Tutorials repo | Combine with documentation repo |
## Issue: Removed obsolete websites
A Google search turns Litmus Chaos-branded websites that are obsolete and/or
unexplained.
Remove or archive related websites that are obsolete.
For any related documentation website that cannot be integrated into the
existing doc repo, make sure there it has a clear explanation as to its purpose,
use, and which version of Litmus Chaos it is compatible with.
Audience:
This issue concerns all users of the documentation.
Type:
This is an infrastructure issue that encompasses all the information on several
websites.
### Context
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> under
`0013-litmuschaos`.
### Possible Implementation
**GraphicQL API**
The following API is one of the first hits on a search of "Litmus Chaos API":
https://litmuschaos.github.io/litmus/graphql/v2.0.0/api.html.
I'm not even sure where the doc repo is (it might be in the API's repo here:
https://github.com/litmuschaos/spectaql). It's clear this is a Litmus Chaos
component, but not whether this documetnation is current or what it is for --
there's no introduction or explanation of the API.
**Tutorials**
The Litmus Chaos Tutorial website (https://litmuschaos.github.io/tutorials/;
repo at https://github.com/litmuschaos/tutorials) seems to have been last
updated in version 2. The first tutorial, "Getting Started", was last updated in
August of 2021.
Having tutorials for the major workflows of Litmus Chaos is a great idea, but
this site looks like it's been abandoned and I'd be nervous about trying the
tutorials on it. Update the site to reassure readers that it's current, and link
to it from the main documentation page. If it's too much work to update the
whole thing, cannibalize it for the most useful workflows and delete the rest of
the site. Or archive the entire site and move on.
**Maintaining the project**
It seems as if a lot of the information about Litmus Chaos that's online was
either written by contributors not directly affiliated with the project or were
initiated by the project and then abandoned. Going forward, we recommend two
things:
1. Maintainers keep tighter control of the Litmus Chaos brand (logo and
trademarks) so that obsolete and unofficial information does not look like
it's a current part of the project to casual observers. Use CNCF resources to
help manage the brand, including website registration.
2. Keep all documentation about the project up to date.
## Issue: Mark a clear "getting started" path
### Overview
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.
The idea is to funnel new users to the Getting Started page, where they can
focus uninterrupted on a streamlined procedure for installing and testing the
product.
Audience:
This issue concerns new users of Litmus Chaos.
Type:
This issue concerns instructional information.
### Context
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> under
`0013-litmuschaos`.
### Possible Implementation
The following links are all labeled "Getting Started" but lead to different
pages:
1. **The _Get Started_ button in the
[Product landing page](https://litmuschaos.io/) banner menu** points to the
[GitHub repo](https://github.com/litmuschaos/litmus).
_Recommendation:_ Re-label the button "Learn more" or "Go to documentation".
2. **The _Get Started_ button on the
[Product landing page](https://litmuschaos.io/)** points to the
[GitHub repo](https://github.com/litmuschaos/litmus).
_Recommendation:_ Re-label the button "Learn more" or "Go to documentation".
3. **The _Get Started_ button on the
[Doc landing page](https://docs.litmuschaos.io/)** points to
[ChaoCenter installation](https://docs.litmuschaos.io/docs/getting-started/installation).
_Recommendation:_ Re-label the button "Learn more" or "Go to documentation". Or, remove this button since the very next section starts with a link to the installation documentation.
4. **The _Getting Started_ link on the
[Doc landing page](https://docs.litmuschaos.io/)** points to
[What is Litmus?](https://docs.litmuschaos.io/docs/introduction/what-is-litmus).
_Recommendation:_ Leave as is. But, reorganize the Installation/Getting Started section in the documentation table of contents (see the next item).
5. **The _Get Started_ table of contents (TOC) entry in the
[Doc page](https://docs.litmuschaos.io/docs/)** left-side menu expands the
section's options in the TOC.
_Recommendation:_ Remove the "Resources" section (that material is covered elsewhere, in "Architecture" and "Concepts"; add a link to that explanation instead). The "Installation" page is a good workflow for beginners to get through installation, configuration, and starting to use the product. Move the contents of the "Installation" page up so that it's a standalone entry called "Getting Started". Move that section to the top of the TOC.
6. **The
[Getting started tutorial](https://litmuschaos.github.io/tutorials/tutorial-getting-started/index.html#0)**
is a standalone tutorial that provides an end-to-end path for a beginner to
install, validate, and run Litmus and execute a chaos experiment.
_Recommendation:_ Link to the tutorial from the main website. Also, see the issue about updating and maintaining the tutorials and other Litmus-branded websites:
https://github.com/litmuschaos/litmus-docs/issues/296.
## Issue: Remove duplicate install instructions
### Overview
Rather than duplicating information in different scenarios (basic vs. advanced
install), rewrite the pages so that no duplication is necessary.
The same applies to anywhere documentation has been duplicated by cut-and-paste.
There are several ways to do this:
- Consolidate the pages so that the separate information is subordinate to the
duplicated information rather than vice versa.
- Put the duplicated material on its own page and link to it. This solution
assumes that making the user click to a common piece of information is a
lesser liability than trying to maintain the same information in two (or more)
places. It usually is.
- Put the dupilcate information on its own page and include in-line everywhere
it's required (not easy to do here, since Markdown doesn't have a mechanism
for that like the Restructured Text ".. include" directive.)
Audience:
This issue concerns new users of Litmus Chaos and users re-installing Litmus
Chaos.
Type:
This issue concerns instructional information.
### Context
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> under
`0013-litmuschaos`.
### Possible Implementation
The following sections (and possibly others) are duplicated between the
[Basic Install](https://docs.litmuschaos.io/docs/getting-started/installation)
and
[Advanced Install](https://docs.litmuschaos.io/docs/user-guides/chaoscenter-advanced-installation):
- Prerequisites
- Install Litmus using Helm
- Install Mongo
- Verify your installation
- Accessing the ChaosCenter
- Hosted (Beta) (information at the top of the tab)
Instead, consider consolidating the basic and advanced install onto one page
using the following outline:
- Installation (one page for both basic and advanced installation)
- Prerequisites (the following two items could be in clickable tabs, or one
after the other with a note to skip the one you don't use.)
- Install Litmus using Helm
- Install Litmus using kubectl (the following two items could be in clickable
tabs, or one after the other with a note to skip the one you don't use.)
- Basic install
- Advanced install
- Verify your installation
- Accessing ChaosCenter
Alternatively, each main bullet item could be its own page, and each page linked
to from its predecessor's "Next steps" heading at the end of the procedure.
## Issue: - Move contributor info out of intro
Move "How to Contribute" out of the
["What is Litmus"](https://docs.litmuschaos.io/docs/introduction/what-is-litmus)
page. "What is Litmus" is introductory conceptual material; "How to Contribute"
is advanced instructional information for a different audience.
Audience:
This issue concerns new users of Litmus Chaos.
Type:
This issue concerns conceptual information.
### Context
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> under
`0013-litmuschaos`.
### Possible Implementation
Remove "How to Contribute" from the
["What is Litmus"](https://docs.litmuschaos.io/docs/introduction/what-is-litmus)
page. Move it to the
[Community](https://docs.litmuschaos.io/docs/introduction/community) page, under
or near the "Contribute" section.
## Issue: 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.
Reorder the "Concepts" table of contents (TOC) so that the items appear in the
same order as they do on the Overview page. In cases where an item is missing
from one or the other, add it so they agree. In cases where the title of the
item is not the same (for example, "Event Triggered Chaos using GitOps" and
"Configuring GitOps"), change one so they agree.
Similarly, make the User Guides TOC agree with the User Guides Overview.
Audience:
This issue concerns all users of Litmus Chaos.
Type:
This issue concerns organizing all documentation information.
### Context
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> under
`0013-litmuschaos`.
### Possible Implementation
Move, rename, and add sections in the User Guide Overview so that it has the
same sections as shown for the User Guides in the TOC:
- Advanced Installation
- Environments
- Chaos Infrastructure
- Injecting Fault
- Resilience Probjes
- Account Settings
- User Management
- Managing Projects
- Teaming
- Configuring GitOps
- Using different image registries
- Uninstall Litmus
Move, rename, and add sections in the Concepts Overview so that it has the same
sections as shown for Concepts in the TOC:
- Chaos Infrastructure
- ChaosHub
- Chaos experiment
- Resilience Probes
- User management
- Projects
- Teaming
- GitOps
- Authentication in ChaosCenter
Also, make sure the TOC entries have consistent captitalization and agree with
the Overview headings. For example, "Chaos experiment" is sentence-style
capitalization; "Chaos Experiment" is title capitalization. Pick one or the
other for the site. Don't mix and match.
## Issue: Move instructional material from Concepts to User Guide
### Overview
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.
Audience:
This issue concerns technical users of Litmus Chaos.
Type:
This issue concerns instructional information.
### Context
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> under
`0013-litmuschaos`.
### Possible Implementation
Here's a suggested course of action for each subsection in Concepts:
| Concept | Documentation change |
| ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ChaosHub -> Prerequisites, Connecting to a Git Repository using ChaosHub | Move to User Guide -> Connecting to a Git Repository |
| ChaosHub -> Syncing a ChaosHub | Move to User Guide -> Syncing a ChaosHub to GitHub |
| ChaosHub -> Editing a ChaosHub | Move to User Guide -> Editing a ChaosHub (expand these instructions) |
| ChaosHub -> Chaos experiments and experiments in a ChaosHub -> View the PreDefined Chaos Experiments | Move to User Guide -> Viewing Predefined Chaos Experiments |
| ChaosHub -> Chaos experiments and experiments in a ChaosHub -> View the Chaos faults, View the fault details | Move to User Guide -> Viewing Chaos Faults |
| ChaosHub -> Disconnect a ChaosHub | Move to User Guide -> Removing a ChaosHub |
| Chaos experiment -> Prerequisites, Defining and executing a chaos experiment | Move to User Guide -> Executing a chaos experiment |
| Resilience Probe | This seems to be conceptual information, but corresponding procedures should certainly be written. Reserve the word "Prerequisites" for conditions that must be met before doing a procedure. For conceptual information, instead say "Related concepts". |
| User management | This section correctly provides conceptual information and points the reader to the corresponding procedures in the User Guide. Model the other sections after this. |
| Projects -> Prerequisites | Again, don't overload the term "Prerequisites"; say "Related concepts". |
| Collaborate with teams | Again, good conceptual overview with pointers to procedures. Don't change, but rename so that the title of the section is a noun, such as "Team collaboration" (suggesting information rather than task information). |
| GitOps | "Prerequisites" to "Related concepts". |
| Authentication | "Prerequisites" to "Related concepts". |
## Issue: Integrate the overview material
### Overview
The following reorganization is suggested:
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.
Audience:
This issue concerns all users of Litmus Chaos.
Type:
This issue concerns conceptual information.
### Context
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> under
`0013-litmuschaos`.
### Possible Implementation
Concepts and Architecture could be integrated into one description of Litmus
Chaos. Both are good but separate views into the working of Litmus Chaos.
"Architecture" describes the separation of the control and execution planes and
provides sequence diagrams of the Chaos processes; "Concepts" describes the
logical entities that make up the Chaos process. It would be helpful if these
two descriptions referenced each other. For example, a section on a Concept
could point out which steps in the sequence diagram the entity is involved in.
## Issue: Consolidate community resource information
### Overview
The following reorganization is suggested:
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.
Audience:
This issue concerns all users of Litmus Chaos, including potential users
(evaluators) and contributors.
Type:
This issue concerns meta-information (project community resources).
### Context
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> under
`0013-litmuschaos`.
### Possible Implementation
Consider combining all community resources under a "Community" menu item in the
website banner header and removing from the technical documentation altogether.
## Issue: Update the User Guide procedures
The User Guides contain stepwise procedures, but these could be written more
clearly.
Audience:
This issue concerns all users of Litmus Chaos.
Type:
This issue concerns instructional information.
### Overview
Procedures are the heart of user documentation, so we discuss them in detail
here. Some guidelines for writing procedures:
- Ensure that tasks are complete. For complex procedures, it's OK to link to
sub-procedures or (usually better) put preliminary tasks in the Prerequisites
section.
- Write instructions in second person (address the readers as "you"). Directly
tell the reader what to do ("Save and run the experiment. You are redirected
to the experiment execution page where the experiment execution steps are
visualized").
- Use gerunds ("-ing" verbs) to title proceure pages; for example "Scheduling a
chaos experiment" rather than "Schedule a chaos experiment".
- Explicitly state which operating systems and platform the installation is for.
This can be done in the Prereqs section.
- In all cases, use conistent naming for the sections as an aid to navigation.
For example, the current documentation uses "Prerequisites" and "Before you
begin" for the same information.
- Similarly, retitle "Learn More" as "Next Steps", and write explanations for
each option
- A basic outline for a procedure should include:
1. Introduction - provide context for the task.
2. Prerequisites: System requirements, operating systems, network, databases -
anything that needs to be in place before the installation.
3. Step by step instructions: Number the steps. Provide only one action per
step. An action is a CLI command, GUI action -- anything that must be done
before moving on to the next step. For CLI commands, file contents, and so
on, provide copyable text. Don't combine steps, especially when they must
be done in sequence.
4. Results (optional; not needed if the results are obvious): What happens
when the procedure is successful. Can include an instruction for how to
verify results.
5. Next steps: Links to one or more procedures that the user might reasonably
want to do next. This might be a link to the next step in a larger
procedure, or to options that are available now that the task is finished.
### Context
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> under
`0013-litmuschaos`.
### Possible Implementation
See the outline in the [Overview](#overview-6).
## Issue: Remove or reduce screen shots
Audience:
This issue concerns all users of Litmus Chaos.
Type:
This issue concerns instructional information.
### Overview
There are many large screen shots in the User Guide procedures. These are
problematic for several reasons:
- They take up a lot of space, pushing the actual text far down the page and
increasing the need to scroll.
- They're difficult to keep up to date: The screenshot should be replaced
anytime there's a change to the menu in question. This is often neglected,
making the documentation inaccurate and in many cases confusing the reader.
- Screen shots are more expensive and difficult to translate than the equivalent
text.
We recommend replacing the 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.
### Context
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> under
`0013-litmuschaos`.
### Possible Implementation
Replace full-size screen shots with a description of the GUI elements being
documented. If a screen shot is necessary, include only a horizontal slice of
the relevant portion.
## Issue: Document functionality from blog posts
### Overview
There are several good articles in the Litmus Chaos blog that expand and explain
Litmus funtionality. Blog posts that run through an end-to-end example would
make good tutorials. If any posts explain core functional capabilities, they
should be included in the Litmus technical documentation so they are findable by
users.
Audience:
This issue concerns all users of Litmus Chaos.
Type:
This issue concerns potentially all types of information.
### Context
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> under
`0013-litmuschaos`.
### Possible Implementation
Here's a list of all the blog posts. Each should be evaluated for technical
documentation content.
- <https://litmuschaos.io/blog/litmuschaos-is-joining-kubecon-cloudnativecon-north-america-2024-3blg>
- <https://litmuschaos.io/blog/introduction-to-k6-load-chaos-in-litmuschaos-4l2k>
- <https://litmuschaos.io/blog/introduction-to-http-chaos-in-litmuschaos-3hn>
- <https://litmuschaos.io/blog/gcp-iam-integration-for-litmuschaos-with-workload-identity-2eai>
- <https://litmuschaos.io/blog/frontend-optimization-at-litmuschaos-1p14>
- <https://litmuschaos.io/blog/litmuschaos-in-2021-the-year-in-review-38cl>
- <https://litmuschaos.io/blog/how-to-contribute-blog-posts-for-litmuschaos-3cnp>
- <https://litmuschaos.io/blog/getting-started-with-litmus-2-0-in-google-kubernetes-engine-4obf>
- <https://litmuschaos.io/blog/part-2-a-beginner-s-practical-guide-to-containerisation-and-chaos-engineering-with-litmuschaos-2-0-253i>
- <https://litmuschaos.io/blog/part-1-a-beginner-s-practical-guide-to-containerisation-and-chaos-engineering-with-litmuschaos-2-0-3h5c>
- <https://litmuschaos.io/blog/litmuschaos-node-memory-hog-experiment-2nj6>
- <https://litmuschaos.io/blog/analysing-chaos-workflows-with-litmus-portal-4e67>
- <https://litmuschaos.io/blog/chaos-engineering-with-litmus-portal-on-okteto-cloud-3g57>
- <https://litmuschaos.io/blog/how-to-use-react-hooks-in-apollo-client-for-graphql-33bh>
- <https://litmuschaos.io/blog/declarative-approach-to-chaos-hypothesis-using-litmus-probes-5157>
- <https://litmuschaos.io/blog/litmuschaos-gitlab-remote-templates-6l2>