diff --git a/analyses/0013-litmuschaos/litmuschaos-analysis.md b/analyses/0013-litmuschaos/litmuschaos-analysis.md new file mode 100644 index 0000000..462f298 --- /dev/null +++ b/analyses/0013-litmuschaos/litmuschaos-analysis.md @@ -0,0 +1,721 @@ +--- +title: LitmusChaos Documentation Analysis +tags: LitmusChaos +created: 2024-08-02 +modified: 2024-10-09 +author: Dave Welsch (@dwelsch-esi) +--- + + + + + + +## 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: +- Website repo: +- Documentation repo: +- Main project repo (for governance and contributor docs): + + +#### Out of scope + +- Other LitmusChaos repos: \* +- 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. + + + +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]. + + + +| 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 + + + +#### 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: + + + +| 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 | + + + +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 diff --git a/analyses/0013-litmuschaos/litmuschaos-implementation.md b/analyses/0013-litmuschaos/litmuschaos-implementation.md new file mode 100644 index 0000000..6510cbd --- /dev/null +++ b/analyses/0013-litmuschaos/litmuschaos-implementation.md @@ -0,0 +1,254 @@ +--- +title: Implementing LitmusChaos Doc Improvements +tags: LitmusChaos +created: 2024-10-24 +author: Dave Welsch (@dwelsch-esi) +--- + + + +## 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. + + + +| 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) | + + + +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. diff --git a/analyses/0013-litmuschaos/litmuschaos-issues.md b/analyses/0013-litmuschaos/litmuschaos-issues.md new file mode 100644 index 0000000..ef9958d --- /dev/null +++ b/analyses/0013-litmuschaos/litmuschaos-issues.md @@ -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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: under +`0013-litmuschaos`. + +### Possible Implementation + +Here's a list of all the blog posts. Each should be evaluated for technical +documentation content. + +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +-