Before contributing, please review the Documentation Contribution Flow. In the following steps you will set up your development environment, fork and clone the repository, run the site locally, and finally commit, sign-off, and push any changes made for review.

• The Meshery Docs site is built using Jekyll - a simple static site generator! You can learn more about Jekyll and setting up your development environment in the Jekyll Docs.

• First install Ruby, then install Jekyll and Bundler.

Note: Windows users can run Jekyll by following the Windows Installation Guide and also installing Ruby Version Manager RVM. RVM is a command-line tool which allows you to work with multiple Ruby environments on your local machine. Alternatively, if you're running Windows 10 version 1903 Build 18362 or higher, you can upgrade to Windows Subsystem for Linux WSL and run Jekyll in Linux instead.

Alternatively, if you are running Windows 10, you may install the Windows Subsystem for Linux:

• WSL1 for Windows build version 1607 or higher.

• Fork and then clone the Meshery repository

  $ git clone https://github.com/YOUR-USERNAME/meshery

• Change to the docs directory

  $ cd docs

• Install any Ruby dependencies

  $ bundle install

• Serve the code locally

  $ make docs

  Note: From the Makefile, this command is actually running $ bundle exec jekyll serve --drafts --livereload. There are two Jekyll configuration, jekyll serve for developing locally and jekyll build when you need to generate the site artifacts for production.

• After making changes, don't forget to commit with the sign-off flag (-s)!

  $ git commit -s -m “my commit message w/signoff”

• Once all changes have been committed, push the changes.

  $ git push origin <branch-name>

• Then on Github, navigate to the Meshery repository and create a pull request from your recently pushed changes!

• See the Meshery Documentation Google Doc for additional reference.
• Theme - https://github.com/vsoch/docsy-jekyll

Goal: Offer comprehensive, organized, and accessible documentation for diverse audiences, from new users to expert contributors. Target Audience:

• Personas: Beginners, developers, admins, operators, security specialists, contributors, users of all experience levels.
• Needs: Varied - learning fundamentals, managing tasks, understanding advanced concepts, contributing code.

• Getting Started: Overview of Meshery, installation options, prerequisites, and setup instructions.
• Installation Guides: Step-by-step instructions for installing Meshery on different platforms (local, cloud, minikube).
• Configuration Guides: Configuring Meshery for different environments (local, cloud, minikube).
• Concepts: Meshery basics (clusters, pods, deployments, services), terminology glossary.
• Use Cases: Demonstrations of common scenarios (web app deployment, data processing pipeline).

A concept page explains some aspect of Meshery. For example, a concept page might describe the Meshery Models object and explain the role it plays as an application once it is deployed, scaled, and updated. Typically, concept pages don't include sequences of steps, but instead provide links to tasks or tutorials.

• Architectural Concepts: Meshery architecture, design, and implementation details. Diagrams illustrating interaction between components, resource dependencies.
• Logical Concepts: Meshery components, resources, and relationships. Diagrams illustrating interaction between components, resource dependencies.

A task page shows how to do a single thing, typically by giving a short sequence of steps. Task pages have minimal explanation, but often provide links to conceptual topics that provide related background and knowledge.

• Task Guides: Step-by-step instructions for common tasks (deploying applications, managing resources).
• Configuration Management: Designing your infrastructure, managing configuration files.
• Lifecycle Management: Discoverying, registering, configuring infrastructure
  • Discovery (MeshSync)
    • Greenfield
    • Brownfield
  • Managing Connections
    • Registering, updating, and deleting connections.
  • Managing Credentials
    • Registering, updating, and deleting credentials.
• Performance Management: Load testing, performance monitoring, resource usage analysis.

• Multi-Meshery Management: Federation, cluster federation, GitOps for configuration management.
• Performance Optimization: Resource usage analysis, profiling tools, tuning techniques.
• GitOps DevOps & CI/CD integration - Integrating Meshery with continuous integration and deployment pipelines.
• Best Practices: Recommendations for securing the Meshery, monitoring performance, managing versions.
• Advanced Concepts: Advanced Meshery concepts, features, and capabilities.
• Air-gapped Environments: Deploying Meshery in air-gapped environments.
• Troubleshooting Guides: Identifying and resolving common errors, debugging techniques.

• Integrations: Integrating Meshery with different infrastructure and systems.
• Extensibility: Customizing Meshery with plugins, adapters, and extensions.
• API Reference: Comprehensive reference for Meshery API objects and fields.
  • Extension Points Meshery extension points for different capabilities.
    • Providers, plugins, adapters, and modules.
• Extensions Meshery adapters, plugins, and modules for different extionsion points.
  • Adapters Integrating Meshery with different infrastructure and extended capabilities.
  • Plugins Meshery plugins for different capabilities.
  • Remote Providers Meshery remote providers for different capabilities.
  • Security and Identity: Authentication, authorization, secrets management, vulnerability scanning.

A tutorial page shows how to accomplish a goal that is larger than a single task. Typically a tutorial page has several sections, each of which has a sequence of steps. For example, a tutorial might provide a walkthrough of a code sample that illustrates a certain feature of Kubernetes. Tutorials can include surface-level explanations, but should link to related concept topics for deep explanations.

• Tutorials: Dedicated walk-throughs with labs and step-by-step instructions using Meshery's features.

A component tool reference page shows the description and flag options output for a Meshery component. For example, a component tool reference page might describe the Meshery CLI and explain the role it plays as an application once it is deployed, scaled, and updated. Typically, component tool reference pages don't include sequences of steps, but instead provide links to tasks or tutorials.

• Command References: Detailed explanations and examples for mesheryctl commands, API resources.
• API Documentation: Comprehensive reference for Meshery API objects and fields.
• Custom Resource Definition Reference: Comprehensive reference for Meshery CRDs.
• Release Notes: Detailed information about version changes, new features, deprecations.
• Glossary: Definitions of common terms, acronyms, and abbreviations.
• Vulnerability Reports: Security advisories, CVEs, and vulnerability reports.

• External Resources: Links to blogs, community forums, case studies, books, training materials.
• Contributing Guide: How to contribute documentation, code, and other resources to the project.
• Community: Highlight community forums, events, contributor guidelines, recognition.
• FAQ: Answers to frequently asked questions.

This high-level outline provides a comprehensive framework for structuring the Meshery documentation, catering to diverse user needs while ensuring information is readily accessible and actionable. By further refining each section with specific content recommendations and considering the needs of specific personas, the documentation can effectively serve as a valuable resource for everyone interacting with Meshery.