Skip to content

Commit

Permalink
fixing formatting
Browse files Browse the repository at this point in the history 
Signed-off-by: Nate W <[email protected]>
  • Loading branch information
@nate-double-u
nate-double-u committed Oct 18, 2024
1 parent 6fc5ea2 commit da04ba6
Showing 1 changed file with 87 additions and 86 deletions.
173 changes: 87 additions & 86 deletions analyses/0013-litmuschaos/litmuschaos-analysis.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,8 @@ author: Dave Welsch (@dwelsch-esi)
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.
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
Expand All @@ -30,9 +30,8 @@ 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.
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:

Expand Down Expand Up @@ -65,8 +64,8 @@ GitHub repo.
#### Out of scope

- Other LitmusChaos repos: <https://github.com/litmuschaos/>\*
- Litmus Software (a completely unrelated company and product based in Massachusetts):
https://litmus.com/*
- Litmus Software (a completely unrelated company and product based in
Massachusetts): https://litmus.com/*

### How this document is organized

Expand Down Expand Up @@ -142,10 +141,10 @@ standards for documentation.
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:
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
Expand All @@ -163,17 +162,17 @@ 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
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
- 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](https://v2-docs.litmuschaos.io/docs/user-guides/schedule-workflow)
point to the `litmusctl` reference. While relevant, this is not the same as
explicit instructions for connecting to a delegate.
Expand All @@ -190,10 +189,9 @@ 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.
[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.
Expand All @@ -213,10 +211,10 @@ New users will be confused as to where to start. There are at least four
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".
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
Expand Down Expand Up @@ -255,8 +253,8 @@ documented in the documentation repo.
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.
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
Expand Down Expand Up @@ -287,8 +285,8 @@ 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.
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
Expand All @@ -305,8 +303,8 @@ 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
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.

Expand All @@ -316,8 +314,8 @@ 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.
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

Expand All @@ -328,20 +326,20 @@ Limit on-site search to the current version of the documentation.
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.
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.
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.
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

Expand Down Expand Up @@ -395,19 +393,19 @@ in the doc repo at the time of this writing, 16 are over two years old.
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.
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.
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.
Expand Down Expand Up @@ -438,7 +436,7 @@ 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 |
Expand Down Expand Up @@ -467,28 +465,28 @@ 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.
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.
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:
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 **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.
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

Expand All @@ -505,7 +503,8 @@ Listed here are the minimal website requirements for projects at graduated
| **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
[maturity-level]:
https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations

<!-- markdownlint-enable line-length -->

Expand Down Expand Up @@ -537,21 +536,21 @@ There is no text-to-speech option available on the site.
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.
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.
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
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
Expand Down Expand Up @@ -581,29 +580,31 @@ 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.
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.
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)
- 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 |
Expand Down Expand Up @@ -666,8 +667,8 @@ case.
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.
Either fix the command-K search functionality or remove the command-K icon from
the search input.

#### Branding and design

Expand All @@ -684,11 +685,11 @@ 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
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.)
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

Expand Down

0 comments on commit da04ba6

Please sign in to comment.