# CONTRIBUTING ## Documentation Sitemap Guide This guide is a reference for where information should be placed in the documentation.\ Top-level items are categories that enable users to access the information they need at a glance. For example, if users need information about integrations, they can select the **Integrations** category. Sidebar items should be sentence-cased. Only capitalize first words. When choosing page names, the title should start with a verb for procedure or task-based content; for example: `Install Bindplane Server`. If the page describes a concept, use a noun or noun-based phrase. For example: `API Keys`. The following information provide guidance for each item in the **observIQ** documentation sidebar. ### Getting Started This section provides essential guidance for users who are just beginning their journey with Bindplane. It covers the initial steps required to set up Bindplane and start collecting metrics, logs, and traces. Documents in this section focus on installation, access to the user interface, and configuring your first collector to ensure a smooth onboarding experience. ### Integration This section focuses on the integration aspects of Bindplane, covering both "Sources" and "Destinations." #### Sources This subsection provides information on various data sources that can be integrated with Bindplane. Each document within this category details the supported platforms and requirements for specific data sources, making it easier for users to understand how to collect metrics, logs, and traces from these sources. #### Destinations Under this subsection, users will find documentation related to configuring destinations for data output. Documents here explain how to set up and configure destinations such as AWS S3 and Google Cloud Managed Service for Prometheus. ### Data Reduction & Transformation This section, "Data Reduction & Transformation," focuses on processors that allow users to modify and enhance telemetry data as it moves through the pipeline. These processors serve as essential tools for data manipulation and enrichment. The processors in this section cover a range of functions, including adding fields, sampling logs, parsing timestamps, and more. They provide users with the capability to transform and reduce data based on specific requirements and conditions, ensuring the data's accuracy, consistency, and relevance. Users can leverage these processors to customize their telemetry data to meet their analysis and monitoring needs. ### Feature Guides The "Feature Guides" section serves as a comprehensive resource for users seeking in-depth knowledge about specific functionalities and features within Bindplane. In this section, users can find detailed documentation on how to effectively utilize these features, enabling them to leverage the full potential of the platform. ### Advanced Setup The "Advanced Setup" section serves as a comprehensive resource hub for users seeking advanced configurations and setups within Bindplane. Covering topics like installation, Kubernetes deployment, configuration, CLI usage, migration assistance, and Terraform integration, this section equips users with the knowledge and guidance required to tackle complex deployment scenarios, optimize performance, and automate various aspects of their Bindplane environment. ### Going to Production The "Going to Production" section is dedicated to providing essential information for users who are preparing to deploy Bindplane in a production environment. This section covers critical topics such as collector architecture, sizing, scaling, and resilience strategies. Users can expect to find guidance on configuring collectors in the collector and gateway modes, understanding the best practices for collector sizing and scaling, and configuring retry mechanisms for robust telemetry data transmission. Overall, this section equips users with the knowledge and strategies required to ensure a reliable and efficient production deployment of Bindplane. ### How-To Guides The "How-To Guides" section offers practical step-by-step instructions and solutions for users looking to address specific tasks or challenges within Bindplane. Users can expect to find detailed instructions and best practices for various scenarios and tasks, making it easier to accomplish specific objectives or troubleshoot common issues. This section serves as a valuable resource for users seeking practical solutions and implementation guidance within Bindplane. ### Support The "Support" section is dedicated to providing users with resources and information related to obtaining assistance and support for Bindplane. It currently includes documents on how to access support and create a support bundle. This section serves as a central hub for users to understand how to seek help, report issues, and gather the necessary information to receive efficient support from the Bindplane team. ### Bindplane Editions The "Bindplane Editions" section focuses on providing information about the different editions of Bindplane, with a particular document titled "Bindplane Enterprise Edition Features." This document likely outlines the key features and capabilities that are exclusive to the Enterprise Edition of Bindplane. Users can refer to this section to understand the specific functionalities and advantages offered by the Enterprise Edition, helping them make informed decisions about their Bindplane deployment and choose the edition that best suits their needs. ## Markdown Documentation Writing Guide Markdown (MD) documents adhere to the MDX formatting convention. To learn more about it, including how to format links, headings, and other elements, please refer to the [MDX documentation](https://mdxjs.com/docs/). ### Standard Components #### Metadata Every MD file MUST begin with `metadata`, including a `title`, an optional `excerpt`, and an automatically updated `updatedAt` field that reflects the document's last modification date. For example: ```jsx --- title: Terraform excerpt: Use Terraform to manage resources updatedAt: '2023-10-27T14:01:06.191Z' --- ``` You can get the current time using the `date` command: ```bash date "+%Y-%m-%dT%H:%M:%S.%jZ" ``` #### Headings Use `#` symbols to create headings of different levels. It's important to note that the page itself should start with a `##` heading, not `#`. The `#` heading corresponds to the title in the metadata. For example: ```jsx ## Terraform ### Documentation ``` Only `##` and `###` headings contribute to the table of contents in your document. Subsequent subsections can use `####`, `#####`, and so on, without being included in the table of contents. ### Custom components #### Admonitions Admonitions can be of four types: `note`, `tip`, `warning`, and `important`. They are used to highlight important information. For example: ```jsx If the `migration-resources.yaml` file exists from a previous migration attempt, move it to a safe location to prevent overwriting it. ``` #### Code Blocks To insert code into your text, use triple backticks (\`\`\`) with an optional language specifier. Supported languages include `bash`, `go`, `tsx`, `yaml`, `javascript` and `text`. For example: ```bash sudo systemctl stop bindplane ``` #### Code Blocks with tabs To display code tabs, wrap all pieces of code with and write labels of code tabs in order: ````md ```bash mkdir bindplane curl -L -o bindplane/bindplane.zip https://... unzip bindplane/bindplane.zip -d bindplane/ sudo mv bindplane/bindplane /usr/local/bin/bindplane mkdir -p ~/.bindplane/ ``` ```bash mkdir bindplane curl -L -o bindplane/bindplane.zip https://... unzip bindplane/bindplane.zip -d bindplane/ sudo mv bindplane/bindplane /usr/local/bin/bindplane mkdir -p ~/.bindplane/ ``` ```` #### Images To include images in your documentation, use the `` component. It accepts two required parameters: src and alt, and one optional parameter: width. * `src`: Specifies the path to the image file. * `alt`: Provides alternative text for accessibility. * `width` (optional): Allows you to adjust the `width` of the image. By default, images take up the entire width of the article. However, if you need to make the image smaller and centered, you can specify a width less than `696`px. Make sure to place your image file in the `public/images/docs` folder and provide the path to the file in the src parameter. For example: ```jsx ``` #### Screenshots When taking screenshots, use a MacBook or similar laptop screen for more consistent resolution and image quality. Screenshot styling is achieved using the [Xnapper](https://xnapper.com/) tool, alongside the following presets: Regular (Used for resource configs and similarly sized screenshots): * Padding: 45 * Inset: 20 * Rounded: 20 * Shadow: 20 * Background: #FFFFFF Wide (Used for wider screenshots, eg. config topology): * Padding: 25 * Inset: 20 * Rounded: 20 * Shadow: 10 * Background: #FFFFFF Narrow (for anything narrower): * Padding: 45 * Inset: 50 * Rounded: 20 * Shadow: 20 * Background: #FFFFFF ## Adding MD Files and Updating the Sidebar In this guide, we'll explain how to add Markdown (MD) files to your documentation and update the Sidebar to reflect the document hierarchy. ### Folder and File Naming Conventions When adding MD files, it's essential to follow consistent naming conventions: * Use lowercase letters for folder and file names. * Replace spaces with hyphens ("-"). For example: * Folder name: `kubernetes-installation` * File name: `install-upgrade-and-uninstall-collectors.md` ### Organizing MD Files Place MD files in their respective sections within the "docs" folder. This ensures a well-structured documentation hierarchy. ### Organizing Other Assets For all other assets, such as PDF files or videos, it's recommended to place them in the public directory within their respective subdirectories. For example: * PDF files: Store them in the `public/pdf` directory. * Videos: Place video files in the `public/video` directory. This organized structure helps keep your assets neatly organized and easily accessible within your documentation project. ### Updating the Sidebar To update the Sidebar and reflect the document hierarchy, modify the `sidebar.md` file. The order of links in this document determines the Sidebar's hierarchy on the documentation pages. Documents within `sidebar.md` should also follow a hierarchical structure, as demonstrated in the example below: ```jsx # Getting started ## [Quickstart Guide](/getting-started/quickstart-guide) ### [1. Install Bindplane Server](/getting-started/quickstart-guide/install-bindplane-op-server) ### [2. Access Bindplane UI](/getting-started/quickstart-guide/access-bindplane-op-ui) ### [3. Install Your First Collector](/getting-started/quickstart-guide/install-first-agent) ### [4. Build Your First Configuration](/getting-started/quickstart-guide/build-your-first-configuration) ## [Google Marketplace Deployments](/getting-started/google-marketplace-deployment) ``` In the example above: * The `#` heading serves as the section title in the Sidebar. * The `##` headings represent subsections within the section. * The `###` headings correspond to individual documents within subsections. By following these guidelines, you can maintain a well-organized and navigable Sidebar that reflects the structure of your documentation. ### Honeycomb We have a white label partnership with Honeycomb. They host their own docs at [honeycombio/third-party-docs](https://github.com/honeycombio/third-party-docs). As of 01/07/2025, @jsirianni has access to this repository. Honeycomb's documentation lead is [Rachel Khoriander](https://github.com/rkhoriander). Rachel can be reached in our shared slack channel #shared-observiq-honeycomb or at . We should prefer slack for initial communication. #### Documentation Contribution Process The Bindplane team is responsible for contributing documentation\ to the Honeycomb repository. If you do not have access to[honeycombio/third-party-docs](https://github.com/honeycombio/third-party-docs), reach out to the Honeycomb team and request\ access. As of right now (01/07/2025) we are copying our entire doc site.\ You can use the script at `scripts/honeycomb-sync.sh` to perform a copy. It assumes you have the following directory structure. The script should be run from the root of the observiq/observiq.com repository. ``` observiq.com/ docs/ third-party-docs/ observiq/ ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.bindplane.com/contributing.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.