Documentation is the most content-heavy part of the Alius platform. Consistent structure across all documentation pages helps users build a mental model of how information is organized, reducing the time spent searching and increasing the time spent learning.

Unified Doc Structure

Every documentation page should follow this general structure, adapting as needed for the content type:

Title

  • Clear, descriptive, and specific
  • Uses sentence case or title case consistently across all docs
  • Immediately tells the reader what the page covers

One-Line Summary

  • A single sentence below the title that summarizes the page content
  • Helps the reader confirm they are on the right page before committing to reading
  • Displayed in a larger or emphasized text style

Target Audience

  • Briefly state who the page is for (beginners, advanced users, hardware engineers, etc.)
  • Helps users self-select whether the content is appropriate for their level
  • Can be shown as a small tag or metadata line

Prerequisites

  • List what the reader should know or have set up before following this guide
  • Link to prerequisite pages when applicable
  • Example: “Before reading this guide, you should have the Agent CLI installed and a device connected.”

Step-by-Step Instructions

  • Numbered steps for sequential procedures
  • Each step should contain one clear action
  • Include expected outcomes after key steps so the user can verify progress
  • Use code blocks for command-line instructions with copy functionality

Example Code

  • Provide working code examples for every concept introduced
  • Use realistic, complete examples — not pseudocode or placeholder values
  • Annotate complex examples with inline comments
  • Show the expected output when relevant

Parameter Explanation

  • For configuration options, API parameters, and CLI flags
  • Present in a structured table or definition list format
  • Include: parameter name, type, default value, valid range, and description
  • Mark required vs. optional parameters clearly

FAQ

  • Anticipate common questions and errors
  • Present as a question-and-answer list
  • Link to relevant external resources or community discussions
  • Keep answers concise and actionable

Next Steps

  • Suggest what the reader should do after completing the current guide
  • Link to related documentation pages
  • Help the reader continue their learning path
  • Link to related guides, API references, tutorials, and community resources
  • Group by type (documentation, community, external)
  • Helps the reader discover content they may not have been looking for

Doc Formatting Rules

  • Use consistent heading hierarchy: H1 for title, H2 for major sections, H3 for subsections
  • Use callout blocks for important notes, warnings, and tips
  • Code blocks must specify the language for syntax highlighting
  • Tables should be used for structured data (parameters, comparisons, compatibility)
  • Images and diagrams should have descriptive captions
  • All links should use descriptive text, not “click here”