Bacalhau Docs
GithubSlackBlogEnterprise
v1.6.x
  • Documentation
  • Use Cases
  • CLI & API
  • References
  • Community
v1.6.x
  • Welcome
  • Getting Started
    • How Bacalhau Works
    • Getting Started
      • Step 1: Install the Bacalhau CLI
      • Step 2: Running Your Own Job
      • Step 3: Checking on the Status of Your Job
    • Creating Your Own Bacalhau Network
      • Setting Up a Cluster on Amazon Web Services (AWS) with Terraform 🚀
      • Setting Up a Cluster on Google Cloud Platform (GCP) With Terraform 🚀
      • Setting Up a Cluster on Azure with Terraform 🚀
    • Hardware Setup
    • Container Onboarding
      • Docker Workloads
      • WebAssembly (Wasm) Workloads
  • Setting Up
    • Running Nodes
      • Node Onboarding
      • GPU Installation
      • Job selection policy
      • Access Management
      • Node persistence
      • Configuring Your Input Sources
      • Configuring Transport Level Security
      • Limits and Timeouts
      • Test Network Locally
      • Bacalhau WebUI
      • Private IPFS Network Setup
    • Workload Onboarding
      • Container
        • Docker Workload Onboarding
        • WebAssembly (Wasm) Workloads
        • Bacalhau Docker Image
        • How To Work With Custom Containers in Bacalhau
      • Python
        • Building and Running Custom Python Container
        • Running Pandas on Bacalhau
        • Running a Python Script
        • Running Jupyter Notebooks on Bacalhau
        • Scripting Bacalhau with Python
      • R (language)
        • Building and Running your Custom R Containers on Bacalhau
        • Running a Simple R Script on Bacalhau
      • Run CUDA programs on Bacalhau
      • Running a Prolog Script
      • Reading Data from Multiple S3 Buckets using Bacalhau
      • Running Rust programs as WebAssembly (WASM)
      • Generate Synthetic Data using Sparkov Data Generation technique
    • Networking Instructions
      • Accessing the Internet from Jobs
      • Utilizing NATS.io within Bacalhau
    • GPU Workloads Setup
    • Automatic Update Checking
    • Marketplace Deployments
      • Google Cloud Marketplace
    • Inter-Nodes TLS
  • Guides
    • Configuration Management
    • Write a config.yaml
    • Write a SpecConfig
    • Using Labels and Constraints
  • Examples
    • Table of Contents for Bacalhau Examples
    • Data Engineering
      • Using Bacalhau with DuckDB
      • Ethereum Blockchain Analysis with Ethereum-ETL and Bacalhau
      • Convert CSV To Parquet Or Avro
      • Simple Image Processing
      • Oceanography - Data Conversion
      • Video Processing
      • Bacalhau and BigQuery
    • Data Ingestion
      • Copy Data from URL to Public Storage
      • Pinning Data
      • Running a Job over S3 data
    • Model Inference
      • EasyOCR (Optical Character Recognition) on Bacalhau
      • Running Inference on Dolly 2.0 Model with Hugging Face
      • Speech Recognition using Whisper
      • Stable Diffusion on a GPU
      • Stable Diffusion on a CPU
      • Object Detection with YOLOv5 on Bacalhau
      • Generate Realistic Images using StyleGAN3 and Bacalhau
      • Stable Diffusion Checkpoint Inference
      • Running Inference on a Model stored on S3
    • Model Training
      • Training Pytorch Model with Bacalhau
      • Training Tensorflow Model
      • Stable Diffusion Dreambooth (Finetuning)
    • Molecular Dynamics
      • Running BIDS Apps on Bacalhau
      • Coresets On Bacalhau
      • Genomics Data Generation
      • Gromacs for Analysis
      • Molecular Simulation with OpenMM and Bacalhau
    • Systems Engineering
      • Ad-hoc log query using DuckDB
  • References
    • Jobs Guide
      • Job Specification
        • Job Types
        • Task Specification
          • Engines
            • Docker Engine Specification
            • WebAssembly (WASM) Engine Specification
          • Publishers
            • IPFS Publisher Specification
            • Local Publisher Specification
            • S3 Publisher Specification
          • Sources
            • IPFS Source Specification
            • Local Source Specification
            • S3 Source Specification
            • URL Source Specification
          • Network Specification
          • Input Source Specification
          • Resources Specification
          • ResultPath Specification
        • Constraint Specification
        • Labels Specification
        • Meta Specification
      • Job Templates
      • Queuing & Timeouts
        • Job Queuing
        • Timeouts Specification
      • Job Results
        • State
    • CLI Guide
      • Single CLI commands
        • Agent
          • Agent Overview
          • Agent Alive
          • Agent Node
          • Agent Version
        • Config
          • Config Overview
          • Config Auto-Resources
          • Config Default
          • Config List
          • Config Set
        • Job
          • Job Overview
          • Job Describe
          • Job Executions
          • Job History
          • Job List
          • Job Logs
          • Job Run
          • Job Stop
        • Node
          • Node Overview
          • Node Approve
          • Node Delete
          • Node List
          • Node Describe
          • Node Reject
      • Command Migration
    • API Guide
      • Bacalhau API overview
      • Best Practices
      • Agent Endpoint
      • Orchestrator Endpoint
      • Migration API
    • Node Management
    • Authentication & Authorization
    • Database Integration
    • Debugging
      • Debugging Failed Jobs
      • Debugging Locally
    • Running Locally In Devstack
    • Setting up Dev Environment
  • Help & FAQ
    • Bacalhau FAQs
    • Glossary
    • Release Notes
      • v1.5.0 Release Notes
      • v1.4.0 Release Notes
  • Integrations
    • Apache Airflow Provider for Bacalhau
    • Lilypad
    • Bacalhau Python SDK
    • Observability for WebAssembly Workloads
  • Community
    • Social Media
    • Style Guide
    • Ways to Contribute
Powered by GitBook
LogoLogo

Use Cases

  • Distributed ETL
  • Edge ML
  • Distributed Data Warehousing
  • Fleet Management

About Us

  • Who we are
  • What we value

News & Blog

  • Blog

Get Support

  • Request Enterprise Solutions

Expanso (2025). All Rights Reserved.

On this page
  • Style, Voice and Tone
  • Friendly and Open
  • Comprehensive and Technically Correct
  • Structure
  • Structure Guidelines
  • Formatting
  • Titles
  • Headers
  • Meta Description
  • Code Blocks
  • Inline Code Blocks
  • Hints
  • Bold and Italics
  • Need Support?
  • Contributing

Was this helpful?

Export as PDF
  1. Community

Style Guide

This guide explains things to keep in mind when writing for Bacalhau’s documentation.

The Bacalhau documentation aims to provide information on how to transform data processing for large-scale datasets to improve cost and efficiency. Our purpose is to open data processing to larger audiences, and our documentation set reflects this intention.

The primary objective of the Bacalhau documentation style guide is to help authors write clear and accurate information while facilitating consistency across all documentation. In this way, we can collectively create valuable learning materials that help developers learn and process data with Bacalhau.

Style, Voice and Tone

Our goal is to use conversational tone that is natural, and friendly towards the reader and also ensure that the document's content is simple and easy to follow.

Friendly and Open

As we write for a large global audience, we aim for a universally accessible voice.

  1. Maintain a friendly, informal tone, but focus on being clear and concise in a knowledgeable manner.

  2. Avoid the use of slangs and colloquial language.

  3. Avoid offensive language in all forms, and toward all identities and cultures.

  4. Write in the second person (e.g. You can…), present tense to guide the reader to their intended outcome.

  5. When writing consider that many users are not native English speakers.

  6. Use languages that encourages readers and walk them through the steps to achieve the outcome they’re looking for.

The goal is for readers to leave with a feeling of accomplishment and satisfaction while gaining information efficiently and solving their problems in a way that helps them thrive with Bacalhau.

Comprehensive and Technically Correct

Our documentation should reflect our purpose, giving the appropriate amount of technical detail and clarity needed in a way that is palatable to all audiences. As best as we can, our documentation should reflect industry-standard practices and inspire trust in our voice and project. To do this,

  1. Ensure that your word choice does not reflect an assumption of the reader’s knowledge level (e.g, using easy, simple, quick, etc) or exclude the detailed explanations or background needed to be successful.

  2. Provide the commands needed to be successful with explanations of the ‘why’ behind the command is preferred when appropriate, with the goal of the reader both gaining their expected outcome and learning in the process.

  3. To ensure clarity, start by briefly specifying the context of the current topic.

  4. Share abbreviations and acronyms with at least one reference to its full name or title on the page to inspire deeper learning into Compute.

  5. In non CLI-based references, capitalize Bacalhau, Docker, Compute and other program/project names.

  6. Test each code snippet and example, walking through each step to ensure accuracy as it's written.

With these guidelines, we can provide a comprehensive set of documentation that is clear, actionable, and helpful.

Structure

The Bacalhau documentation set should include articles and tutorials that have a consistent structure, which includes an introduction and the procedural steps necessary for a reader to get to their expected outcome.

Structure Guidelines

The specific structure depends on the type of documentation you are writing. On general note, the documentation should include: an introduction, a conclusion, and any prerequisites necessary for a reader to get started.

Most of the tutorials and examples we publish are procedural, which walk the reader through accomplishing a task step-by-step. The structure for a procedural documentation should be:

Title (H1)
Introduction (paragraph)
Prerequisites (H2)
Doing the First Thing (H2)
Doing the Next Thing (H2)
…
Doing the Last Thing (H2)
Need Support? (H2)
Contributing (H2)

If the documentation is conceptual:

Title (H1)
Introduction (paragraph)
Prerequisites (optional) (H2)
Subtopic 1 (H2)
Subtopic 2 (H2)
…
Subtopic n (H2)
Need Support?  (H2)
Contributing (H2)

In this way, readers can learn and hop to pertinent information as they need efficiently, and find answers when they need.

Formatting

Titles

❌ Get started with bacalhau
✅ Get Started with Bacalhau

Headers

Titles should be an H1 header. Introduction, prerequisites, steps, and conclusion should all have H2 headers.

Title (H1)
Introduction (paragraph)
Prerequisites (H2)
Doing the First Thing (H2)
Doing the Next Thing (H2)
…
Doing the Last Thing (H2)
Need Support? (H2)
Contributing (H2)

Meta Description

All pages in the document should have a front-matter description which briefly summarizes the contents of a webpage.

---
description: This shows up in the search results, underneath the title tag.
---

Code Blocks

Use Code Block formatting option for the code blocks. It should be used for:

  1. Commands the reader needs to execute to complete the tutorial

  2. Files and scripts

  3. Terminal output

  4. Interactive dialogues that are in text

bacalhau docker run ubuntu echo Hello World

Do not include the command prompt ($ or #) in the code block

Inline Code Blocks

Use a Code formatting option for inline code examples. It should be used for:

  1. Command names, like bacalhau docker run

  2. File names and paths, like /inputs

  3. Example URLs, like http://your_domain

  4. Command flag like --gpu

Hints

The hints include:

  1. info: Use to add some supplementary information to a section or point that could benefit from some highlighting to draw the reader’s attention.

  2. success: Use to add some guidance on how to carry out a step and show achievements.

  3. warning: Use to make the reader aware they need to be careful when acting on some advice.

  4. danger: Use to indicate that there are dangers or consequences associated with some information or steps.

Here’s an example of an Info hint:

Info hints are great for showing general information, or providing tips and tricks.

Bold and Italics

Bold text should be used for:

  1. list item

  2. Emphasis on words, project names etc

Italics should be used in inline list. For example (e.g, easy, simple, quick, etc)

Need Support?

Contributing

PreviousSocial MediaNextWays to Contribute

Was this helpful?

Our documentation is written in . The following rules explain how we organize and structure our writing.

All titles should follow .

If have questions or need support or guidance, please reach out to the

If you have any hints, tips or suggestions to add, check out the different .

Markdown markup language
title case capitalization structure
Bacalhau team via Slack (#bacalhau channel)
ways to contribute to Bacalhau