[Docs] OpenSearch Dashboards documentation gaps

[ashwin-pc]

OpenSearch Dashboards documentation gaps

This is just my take on some of the documentation gaps that we have. Would love to start a discussion on the topics and how we can address them incrementally. This outlines some of the gaps in documentation we have today, both in the form of readme's within the repo and as a separate doc site.

Table of contents

• Architecture
• Development
• Core
• Plugins
• Packages
• Testing
  • General
  • Unit
  • Functional
• Misc
  • Docker

Architecture

• Overall architecture of OSD
• How Client and server interact (OSD)
• How OSD and OS Engine interact
• The many different ways to setup the Repo:
  • With and without security
  • For Core development and testing
  • For plugin development and testing
• State management, storage, persistence, error handling, data validation etc

Development

We have gaps in core developer docs too but I am not going to cover this here because its goal is slightly different from documenting whats under the hood for OSD.

Some important topics here however are:

• Setup, build, running tests
• Cleaning and troubleshooting
• Working with PR's
• Releasing
• Installing and working with external plugins

Core (./src/core)

• We have a core readme ./src/core/readme, but It can be more detailed considering that it is the bedrock for all plugins and how they work
• What should be in core and what should not?
• API's
• Readme's that are current here, such as testing and principles, move them to a more easy to find location. We should not have 2 Testing docs. It causes confusion.
• How the setup and start api's in a plugin contract work

Plugins

We need a high level readme for the plugins folder (./src/plugins) that oulines the general structure of the plugins folder and also the different types of plugins that someone can use as a quick reference if they are trying to build something or do something similar. Some of the things we need to cover here are:

• What are plugins
• Difference between a plugin and package
• Plugin lifecycle
• Conventions, Testing methodology (Can just be moved over from src/core)
• Types of plugins (Core, External, Example)
• How to create a plugin
• How to release a plugin
• How to install a plugin
• Enable and Disable a plugin

Some of the things we need to do for core plugins

• Not all of them are equally important and need to be categorized.
• Every plugin needs to have a useful readme.
• Plugins need to be audited to see if they still make sense or if they should be deprecated or pulled out as an external plugin. e.g. telemetry

Some categories for the plugins can be: (More input appreciated here)

• Application
• Library
• Visualization

Plugin list:

• [APP] advanced_settings
• [___] apm_oss
• [___] bfetch
• [___] charts
• [___] console
• [APP] dashboard
• [LIB] data
• [___] dev_tools
• [APP] discover
• [LIB] embeddable
• [LIB] expressions
• [APP] home
• [___] index_pattern_management
• [___] input_control_vis
• [___] inspector
• [___] legacy_export
• [___] management
• [___] maps_legacy
• [___] navigation
• [___] newsfeed
• [___] opensearch_dashboards_legacy
• [___] opensearch_dashboards_overview
• [___] opensearch_dashboards_react
• [___] opensearch_dashboards_usage_collection
• [___] opensearch_dashboards_utils
• [___] opensearch_ui_shared
• [___] region_map
• [LIB] saved_objects
• [___] saved_objects_management
• [___] share
• [___] telemetry
• [___] telemetry_collection_manager
• [___] telemetry_management_section
• [___] tile_map
• [___] timeline
• [___] ui_actions
• [___] url_forwarding
• [___] usage_collection
• [___] vis_default_editor
• [___] vis_type_markdown
• [___] vis_type_metric
• [___] vis_type_table
• [___] vis_type_tagcloud
• [___] vis_type_timeline
• [___] vis_type_timeseries
• [___] vis_type_vega
• [___] vis_type_vislib
• [___] vis_type_xy
• [___] visualizations
• [APP] visualize
• [APP] wizard

Sample readme for a plugin

# Plugin_name

Category: application, service, helper etc

Brief description of what it does

## Usage

How to use the plugin, ideally with code snippets or links to example plugins in `./examples` with instructions on how to use them.

#```
Code snippets
#```

## Setup Contract
We need this in the readme because sometimes it is quite hard to tell from the `plugin.ts` file what the start and setup contracts look like. e.g. `src/plugins/visualize/public/plugin.ts`

## Start Contract

Packages

We need similar to plugins a high level Readme (We already have one but it does not cover some important points) with the following information:

• What are packages?
• How do they differ from plugins
• Update the exisitng readme to remove Mocha as a testing approach (Since we deprecated this)

Similar to plugins, each of the packages should also have a readme e.g. packages/osd-pm/README.md

List of packages:

Package	Audit	Readme
opensearch-datemath	x	x
opensearch-eslint-config-opensearch-dashboards		x
opensearch-safer-lodash-set	x
osd-ace	x	Deprecation path
osd-analytics	x	x
osd-apm-config-loader	x	Needs more info
osd-babel-preset	Why we need this
osd-config		More info
osd-config-schema	Custom config validation apparently for better security. Not sure if that is srtill true since no one is actively looking at this for vulnerabilities
osd-dev-utils	x	x
osd-eslint-import-resolver-opensearch-dashboards	x
osd-eslint-plugin-eslint		x
osd-expect	Do we still need this?
osd-i18n
osd-interpreter	x	x
osd-logging	Need a future path here
osd-monaco		A lil more info would help here
osd-opensearch
osd-opensearch-archiver	x	x
osd-optimizer
osd-plugin-generator		Add release instructions here
osd-plugin-helpers
osd-pm
osd-spec-to-console
osd-std		x
osd-telemetry-tools	x
osd-test	Path forward
osd-test-subj-selector	x
osd-ui-framework	(Deprecated) Path forward
osd-ui-shared-deps		More info appreciated
osd-utility-types	Do we need this
osd-utils		x

Audit: Check to see if this is necessary, or deep-dive into what it does Readme: Readme is either missing or does not have enough information

The readme's here too can have a sample template similar to the plugins for consistency

Testing

Unit testing

given the current plugin architecture, additional docs for unit testing are required so that it is easier write these tests to avoid bad testing patterns or unnecessary duplicate mocks

• How to use the plugin mocks. Many plugins (Ideally this should be all plugins) expose mocks that other dependent plugins can use to test their functionality when they are using a primary plugins API. e.g. src/plugins/saved_objects_management/public/plugin.test.ts
• Basic plugin tests that are expected.
• Common testing patterns and gotchas

Functional testing

Currently functional testing is a pain. While this needs to be improved, good docs can go a long way in making it easier to write these tests.

• How to setup the Functional test env
• Env requirements (Linux, x86, specific chrome/Chromium version)
• Difference between Selenium and Cypress tests
• Debugging & Troubleshooting

Miscellaneous

Other miscellaneous documentation gaps

Docker

• The different configurations available
• Docker env variables (available ones and how to add one)
• How to use with docker

[ashwin-pc]

Suggested approach to fill in these gaps:

• Identify/Assign an SME to each topic
• Determine if additional research is needed
  • If additional research is needed, timebox and research
• Create an issue and document the topic in a readme in the repo or on the doc site

[vagimeli]

@ashwin-pc Let's sync to discuss content strategy and development.