Documentation Standards

Documentation Standards (Docs-as-Code)

This portal ingests .md files automatically from satellite GitHub repositories (nkz-os/nkz and module repos). To ensure correct parsing by Astro/Starlight and maintain architectural consistency, every ingested markdown file MUST strictly adhere to these standards.

1. Mandatory Frontmatter (YAML)

Every markdown file must begin with exactly this block of YAML:

---
title: Technical Title (Required)
description: A concise, direct technical summary (Required)
sidebar:
  order: [integer] (Required)
  label: Optional shorter label for sidebar
---

Definitions:

• title: String. The primary <h1/> of the page. Must be precise and lack marketing adjectives. (e.g., LiDAR Point Cloud Ingestion, NOT Amazing LiDAR Integration).
• description: String. Used for SEO <meta> and component previews. State what the component does or what the guide accomplishes.
• sidebar.order: Integer. Controls the display sequence within its directory. Lower numbers appear higher. Files without order fall to alphabetical sorting, breaking the UX hierarchy.

2. Tone and Style Directives

1. Neutral and Direct: The target audience consists of Software Engineers, DevOps, GIS Technicians, and University Researchers. Eliminate commercial tone, marketing adjectives, or condescending language.
2. Assumed Baseline: Do not explain fundamental concepts (e.g., “Docker is a containerization platform”). Explain how NKZ OS leverages Docker, K8s, TimescaleDB, or WebGL to solve specific domain problems.
3. Code Blocks over Prose: Prefer providing deterministic CLI commands, YAML manifests, or JSON payloads over long-winded paragraphs.

3. Images and Assets (Logos & Screenshots)

To provide a professional look for the modules catalog, developers must include a logo and a UI screenshot in their documentation. The Docs-as-Code engine automatically supports image ingestion (.png, .jpg, .jpeg, .svg, .webp, .gif).

Instructions for Developers (Fool-proof Guide):

1. Placement: Save your image files (e.g., logo.png or screenshot.jpg) directly inside the docs/ folder of your repository, right next to your index.md file. Do not create assets/ or images/ subdirectories inside docs/.
2. Referencing: Embed the images in your index.md using standard relative markdown syntax starting with ./:

   ![Module Logo](./logo.png)
   
   ![UI Screenshot](./screenshot.jpg)

The ingestion engine will automatically download these binaries and Astro will optimize and render them on the website.