How to Use This Documentation¶
This guide will help you navigate and make the most of the Waveshift documentation. Understanding the visual cues and formatting will help you find information quickly and avoid common pitfalls.
Navigation¶
The documentation is organized into several main sections:
- Getting Started - Installation guides and initial setup
- CLI Reference - Detailed command documentation for wavectl
- Configuration - Configuration file management
- Workflows - Common usage patterns and examples
- User Guide - System architecture and operations
- Troubleshooting - Solutions to common issues
Use the left sidebar to navigate between pages, and the right sidebar shows the table of contents for the current page.
Understanding Callout Boxes¶
Throughout this documentation, you'll see colored callout boxes that highlight important information. Each type has a specific purpose:
Information and Notes¶
Information Boxes
Blue/cyan boxes like this provide general information, helpful context, or references to external documentation.
When you'll see this: References to AWS documentation, explanations of concepts, or additional context.
Note Boxes
Standard blue notes provide supplementary information that's good to know but not critical.
When you'll see this: Technical details, alternative approaches, or background information.
Summary Boxes
Light blue summary boxes provide quick overviews or TL;DR content.
When you'll see this: Section summaries or quick reference information.
Helpful Tips and Success¶
Tip Boxes
Green tip boxes highlight helpful suggestions, best practices, or time-saving shortcuts.
When you'll see this: Best practices for configuration, efficiency tips, or recommended approaches.
Example: "Use the --help flag with any wavectl command to see all available options."
Success Indicators
Green success boxes confirm when you've completed a step correctly or show expected positive outcomes.
When you'll see this: Verification steps, expected successful outputs, or completion confirmations.
Example: "If you see your AWS account ID in the output, authentication is successful!"
Questions and Help
Light green question boxes address common questions or provide help on specific topics.
When you'll see this: FAQ sections, clarifications, or answers to anticipated questions.
Warnings and Cautions¶
Warning Boxes
Orange/yellow warning boxes alert you to important prerequisites or actions that require attention before proceeding.
When you'll see this:
- Prerequisites that must be met before starting
- Configuration requirements
- Authentication checks
- Directory setup requirements
Example: "Ensure you're authenticated with AWS before running deployment commands."
Caution Boxes
Similar to warnings but indicate situations where you should proceed carefully.
When you'll see this: Operations that might have side effects or require careful consideration.
Errors and Problems¶
Danger Boxes
Red danger boxes warn about destructive operations or critical issues that could cause data loss or service disruption.
When you'll see this:
- Destructive operations (e.g.,
--destroyflags) - Actions that permanently delete resources
- Commands that cannot be undone
Example: "The destroy operation permanently deletes all AWS resources. Ensure you have backups before proceeding."
Failure Indicators
Red failure boxes show common error scenarios or things that might go wrong.
When you'll see this: Common failure scenarios, missing dependencies, or configuration errors.
Known Issues
Red bug boxes highlight known bugs, limitations, or workarounds.
When you'll see this: Platform limitations, known bugs, or temporary workarounds.
Examples and References¶
Example Boxes
Purple example boxes contain practical examples, code samples, or real-world scenarios.
When you'll see this:
- Complete workflow examples
- Configuration examples
- Command usage examples
Quotations and Citations
Gray quote boxes contain references, quotations, or citations from external sources.
When you'll see this: Official documentation references or important quotes.
Collapsible Sections¶
Some information is hidden by default to keep pages clean. Look for collapsed boxes with a ▶ arrow:
Click to Expand This Example
When you see a collapsed section like this, click on it to reveal the content. This is useful for:
- Optional detailed information
- Platform-specific instructions you might not need
- Reference material that's good to have but not always needed
Common collapsible sections:
- AWS dependency installation (you might already have these installed)
- Detailed AWS configuration (if you're already familiar)
- Advanced options and flags
Code Blocks and Tabs¶
Syntax Highlighting¶
Code blocks are syntax-highlighted for readability:
Platform-Specific Tabs¶
When instructions differ by platform, you'll see tabbed sections:
Click the tab for your operating system to see relevant instructions.
Search Functionality¶
Use the search bar at the top of the page to quickly find information:
- Search by command name: e.g., "deploy", "sites", "configure-hub"
- Search by topic: e.g., "AWS authentication", "WireGuard", "configuration"
- Search by error message: e.g., "permission denied", "connection refused"
The search is comprehensive and includes all documentation pages, code examples, and configuration references.
Common Visual Patterns¶
Prerequisites at the Start¶
Most deployment or configuration pages start with prerequisite warnings:
Example: Typical Prerequisites Section
AWS Authentication Required
Before proceeding, ensure you're authenticated with AWS.
Use a Dedicated Directory
Run commands in a clean, dedicated directory.
Action: Always read these before starting any procedure.
Step-by-Step Instructions¶
Deployment and configuration guides use numbered steps:
Step 1: Initialize
Step 2: Deploy
Follow steps in order for the best results.
Verification Steps¶
After important operations, look for success boxes that help you verify:
Tips for Using This Documentation¶
Best Practices
- Start with Getting Started - Even if you're experienced, skim the installation guide to understand Waveshift-specific requirements
- Read warnings first - Yellow warning boxes contain critical prerequisites
- Use the search - Don't scroll endlessly; search for specific commands or topics
- Check examples - Purple example boxes show complete, working examples
- Use
--help- Every wavectl command has built-in help:wavectl <command> --help - Keep the CLI reference handy - Bookmark the CLI reference for quick command lookups
When Things Go Wrong
- Check danger/warning boxes - Did you miss a prerequisite?
- Look for failure boxes - Common errors are documented with solutions
- Visit Troubleshooting - The troubleshooting section covers common issues
- Use search - Search for your error message
- Check authentication - Many issues stem from AWS authentication problems
Quick Reference¶
Admonition Priority (What to Read First)¶
When a page has multiple callout boxes, prioritize them in this order:
- 🔴 Danger - Read immediately (destructive operations)
- 🟡 Warning - Read before proceeding (prerequisites)
- 🟢 Tip - Read for best practices
- 🔵 Info/Note - Read for context
- 🟣 Example - Read for practical demonstrations
Common Command Reference¶
Keep these handy:
# Get help on any command
wavectl <command> --help
# Check AWS authentication
aws sts get-caller-identity
# View configuration
cat wavectl.json
# Health check
wavectl health-check
Need More Help?¶
If you can't find what you need in the documentation:
- Search the documentation using the search bar
- Check the CLI Reference for detailed command information
- Review Troubleshooting for common issues and solutions
- Contact Support - Reach out to Blackfire Technology support
Documentation Version: This documentation is for Waveshift deployed via wavectl CLI.
Company: Blackfire Technology Ltd
Target Deployment: AWS-based Waveshift infrastructure