Skip to main content

Satellite Spectrum Handbook Style Guide

This style guide establishes the rules for writing, formatting, referencing, and translating content for the Satellite Spectrum Handbook. These rules are enforced by our automated agents and are mandatory for all contributors.

1. Tone and Language Style​

  • Easy to Understand: Write in clear, simple English. Avoid overly dense administrative or legal jargon. When technical terms (e.g., NGSO, epfd, bringing into use) must be used, explain them immediately using analogies.
  • Factual & Objective: All material must be strictly objective, factual, and educational.
  • Zero Commercial Bias: Absolutely no marketing, product pitching, self-promotion, or biased wording. Do not recommend or praise specific commercial operators, launchers, or hardware manufacturers unless they are required as factual context (e.g., mentioning SpaceX's Starlink or OneWeb purely as examples of non-geostationary mega-constellations).
  • Inclusive & Neutral: Avoid regional biases. Do not assume the reader only cares about US FCC regulations; balance with ITU-R, Ofcom (UK), ISED (Canada), and other global administrations.

2. Formatting & Markdown (MDX)​

  • Admonitions: Use native Docusaurus admonitions for highlighting important rules or tips: 
    :::important
    This is a critical regulatory milestone.
    :::
  • Diagrams: Use Mermaid blocks to explain complex orbital configurations or filing workflows:
    • Mermaid Formatting & Color Palette:
      • Centering: Mermaid diagrams must always be centered horizontally on the page.
      • No Horizontal Scrolling: Keep diagrams simple and vertical so they fit cleanly on mobile and desktop views. Split complex or dense diagrams into multiple smaller diagrams placed sequentially.
      • Consolidated Theme: All Mermaid elements are styled globally via src/css/custom.css. Do not use inline styles or random custom colors in individual diagram codes, except for subgraph cleanNode layout borders.
      • Subgraph Template: For subgraphs in Mermaid diagrams, always define and apply the cleanNode template to keep backgrounds transparent and use a clean dark blue border:
      • Visual Palette: Subgraphs use (classDef cleanNode fill:none,stroke:#102a43,stroke-width:1px;) with a clean Slate border (#cbd5e1/#475569), replacing the default bright yellow/gold backgrounds. Nodes use a clean white/dark-slate fill with Slate borders and rounded corners.

3. SEO Requirements​

Every chapter must be highly optimized for search engines to ensure visibility for regulatory professionals and beginners:

  • Title: Under 60 characters, keyword-rich, and unique.
  • Description: Under 160 characters. Must summarize the chapter accurately and naturally include target keywords (e.g., "satellite spectrum licensing", "ITU coordination process").
  • Heading Hierarchy:
    • The page title in frontmatter generates the only <h1> on the page.
    • Do not use # in the body. Start body headings with ## (H2) and nested sections with ### (H3).
  • Internal Linking: Interlink pages using descriptive anchor text (e.g., Read about [landing rights](./landing-rights.md)). Never use generic phrases like "click here" or "learn more".

4. References & External Links​

All regulatory statements must be referenced to maintain professional credibility:

  • Format: State the administration or body, followed by the specific regulation or recommendations document name.
  • Examples:
    • ITU Radio Regulations Article 9 (2020 Edition)
    • FCC Title 47 CFR Part 25
    • Ofcom Space Spectrum Strategy (2022)
  • Links: Provide direct links to official public sites (e.g., ITU.int, FCC.gov, Ofcom.org.uk) where readers can download or read the source documents. Ensure the links are permanent and secure (HTTPS).

5. Chapter End Navigation & Related Content​

Every handbook page must end with a standard navigation section to guide the reader:

---

## Next Steps
* **Next Topic**: [Name of Next Chapter](./next-chapter-file.md) - Brief sentence describing what the next chapter covers.
* **Related Concepts**:
  - [Concept A](./another-file.md) - Quick explanation of how it relates.
  - [Concept B](./yet-another-file.md) - Quick explanation.
* **Further Reading**:
  - [ITU filing guide](https://www.itu.int/...) - Reference PDF or portal.