Skip to content

Commit

Permalink
formatting & spelling updates
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 28, 2024
1 parent 3802d93 commit d43d566
Showing 1 changed file with 82 additions and 91 deletions.
173 changes: 82 additions & 91 deletions analyses/0013-litmuschaos/litmuschaos-implementation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,11 +38,11 @@ The top-level documentation recommendations for this project are:

- 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
- 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
- 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
Expand All @@ -52,17 +52,17 @@ The top-level documentation recommendations for this project are:
- 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
- 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
- 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)
Expand All @@ -72,8 +72,8 @@ The top-level documentation recommendations for this project are:
- 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
- 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
Expand All @@ -89,11 +89,11 @@ Ideally, this includes:
- 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.
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.

Expand All @@ -105,117 +105,109 @@ project website.

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 docuemented 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
- 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 "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 instllation](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](https://v2-docs.litmuschaos.io/tutorials) | [Getting started tutorial](https://litmuschaos.github.io/tutorials/tutorial-getting-started/index.html#0) |
| 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](https://v2-docs.litmuschaos.io/tutorials) | [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
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
- **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.
- **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 signfiicantly between user roles, write a separate
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.
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.
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:
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 conistent when writing similar sections, especially procedures. Using a
- Be consistent when writing similar sections, especially procedures. Using a
template can make this easier.
- Use gerunds ("-ing" verbs) to title proceure 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.
- 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 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
- 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.
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.
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.

Expand All @@ -224,18 +216,18 @@ Expand the glossary. Make the glossary purely a reference that defines terms.
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.

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.

Clean up the backlog of documentation issues.

Expand All @@ -248,13 +240,12 @@ Make sure documentation issues have complete descriptions.
- 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.
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.
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.

Expand Down

0 comments on commit d43d566

Please sign in to comment.