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.
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:
You can get the current time using the date command:
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:
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:
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:
Code Blocks with tabs
To display code tabs, wrap all pieces of code with and write labels of code tabs in order:
Images
To include images in your documentation, use the <ImageBlock/> 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 thewidthof 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 than696px.
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:
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 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-installationFile 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/pdfdirectory.Videos: Place video files in the
public/videodirectory.
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:
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.
As of 01/07/2025, @jsirianni has access to this repository. Honeycomb's documentation lead is Rachel Khoriander. Rachel can be reached in our shared slack channel #shared-observiq-honeycomb or at [email protected]. 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 tohoneycombio/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.
Last updated
Was this helpful?