From 734dda476e5d0c2fd658aa5e6000c092a4f241c8 Mon Sep 17 00:00:00 2001 From: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Date: Mon, 19 Aug 2024 13:01:04 -0700 Subject: [PATCH] Fix API analysis Removed references to unrelated commercial software site litmus.com APIs that I mistakenly thought were part of the Litmus Chaos project. Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> --- .../0013-litmuschaos/litmuschaos-analysis.md | 53 ++++++++----------- 1 file changed, 22 insertions(+), 31 deletions(-) diff --git a/analyses/0013-litmuschaos/litmuschaos-analysis.md b/analyses/0013-litmuschaos/litmuschaos-analysis.md index d8d304e..bacff42 100644 --- a/analyses/0013-litmuschaos/litmuschaos-analysis.md +++ b/analyses/0013-litmuschaos/litmuschaos-analysis.md @@ -2,7 +2,7 @@ title: LitmusChaos Documentation Analysis tags: LitmusChaos created: 2024-08-02 -modified: 2024-08-13 +modified: 2024-08-19 author: Dave Welsch (@dwelsch-esi) --- @@ -65,6 +65,8 @@ GitHub repo. #### 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 @@ -157,23 +159,13 @@ first ToC heading). There is high level, conceptual “About” content. This content is split between at least two sections, "Introduction" and "Concepts". -The documentation seems feature-complete. However, the documentation resides on -several websites. The tutorials have their own site, and The documentation for -the APIs is on various GitHub Pages websites. +The main documentation site seems feature-complete. However, the documentation +resides on several websites. The tutorials have their own site - - -| Docs | URL | -| --------------- | -------------------------------------------------------------- | -| Portal API | | -| General API | | -| Instant API | | -| Email analytics | | -| Legacy previews | | -| Tutorials | | - -The API documentation seems complete, but there is no readily available -introduction explaining the differences between them. +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. @@ -293,11 +285,9 @@ 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. -Write an introduction to the APIs, explaining the purpose of each and linking to -their reference documentation. The API docs might be an exception to the -documentation single-source rule, since the references are generated from code -or from YAML files in the code repo. Make sure, however, that semantic -information and examples are included in the API references. +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 @@ -475,7 +465,7 @@ Litmus has separate websites for its documentation and for its project website. The project website has been replaced: The [new project repo]() -seems to be currently maintained and was last touched in May. +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 @@ -492,7 +482,7 @@ the following documentation is maintained separately, in different locations: - 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 a YAML file in the main code repo. There is +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. @@ -544,13 +534,13 @@ 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 (some of the APIs, the experiment library) +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 pages, and the tutorial page all use different layouts. +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 @@ -616,13 +606,13 @@ 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://v2-docs.litmuschaos.io/tutorials) | https://github.com/litmuschaos/tutorials | Google Codelab? | -| APIs | https://github.com/litmuschaos/litmus/tree/master/mkdocs | MkDocs | +| [APIs][api-site] | https://github.com/litmuschaos/litmus/tree/master/mkdocs | MkDocs | @@ -631,7 +621,7 @@ 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 APIs adds complexity and takes time. +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. @@ -649,7 +639,7 @@ Combine all the website pages into a single repo. Ideally, this includes: - The project website - The documentation -- The APIs +- The API - Tutorials Use a single website technology stack for the entire site. @@ -712,7 +702,7 @@ No recommendations. ##### Rating values -The numeric rating values used in this document are as follows +The numeric rating values used in this document are as follows: 1. Not present 2. Needs improvement @@ -720,6 +710,7 @@ The numeric rating values used in this document are as follows 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-issues.md