docs/static/v0.8/project/contributing/contributing-docs-structure/index.html
Providing well-structured, easy-to-navigate documentation tailored for a diverse audience—from beginners to experts.
We first identify who this documentation serves before diving into how it’s organized. By clarifying different user personas, we can better direct them to relevant sections:
Users
Contributors & System Integrators
Administrators
After defining our audience, we introduce the overall structure of Meshery’s documentation. Each section below addresses a different need, level of expertise, or user focus.
This section focuses on giving new and experienced users an overarching understanding of Meshery, including basic setup, installation options, and general operations.
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).
Tasks & Operations (User Guide)
Concepts: Basic Meshery concepts (clusters, pods, deployments, services), terminology glossary.
Use Cases: Demonstrations of common scenarios (web app deployment, data processing pipeline).
This section provides a concise, hands-on introduction for newcomers, referring back to “Overview and Installation” for more details.
Concept pages describe what a particular aspect of Meshery is, but not how to do it step-by-step. They provide background knowledge and link out to related tasks or tutorials.
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 infrastructure, managing configuration files.
Lifecycle Management: Discoverying, registering, configuring infrastructure
Performance Management: Load testing, performance monitoring, resource usage analysis.
Designed for platform engineers, operators, DevOps, and other advanced users who require deeper insights into Meshery’s configuration, security, and maintenance.
Meshery’s extensibility allows for seamless integration with existing systems and the addition of new capabilities through adapters, plugins, and extensions.
Extensibility: Customizing Meshery with plugins, adapters, and extensions.
Integrations: Meshery Models. Integrating Meshery with different infrastructure and systems.
Extensions: List of all of Meshery adapters, plugins, and modules for different extension points.
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.
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.
mesheryctl commands, API resources.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.