helixml / docs

Content Structure - helixml/docs

Content Structure for https://github.com/helixml/docs/

The documentation for this project follows a structured approach, making it easy to navigate and find the required information. The main components of the content structure include sections, pages, and navigation.

Sections

Sections in the documentation are organized based on user goals and feature content. They serve as a group for related content, assisting users in navigating to child topics.

Parent

Each top-level entity has one or more parents, which are groups of related feature content. Parent topics provide a consistent user experience and help users navigate to child topics.

Child

This level of the information architecture includes concepts, tasks, or reference topics.

Directory Structure

The repository’s parent directory is structured as follows:

  • _index.md: A landing page for the child topics, containing conceptual content.
  • Task topics: Each with a directory and a markdown file.

Documentation Design

The documentation website uses a modern design approach to make the technical documentation accessible, modern, and scalable. The design includes:

  • Navigation to preview primary topics.
  • A left-hand sidebar that outlines key topics with nested related topics underneath.
  • A floating table of contents.

Kinds of Documentation

The documentation includes different kinds, such as:

  • Folder: A collection of resources that are grouped together and can share permissions.
  • TextPanelCfg: A configuration for a text panel in Grafana, with properties like CodeLanguage, CodeOptions, and content.

Adding Docs to the Repository

To add documentation to the repository, follow these steps:

  1. Create a docs/sources folder if it doesn’t already exist.
  2. Create the folders and structure for the documentation.
  3. Add front matter to each Markdown file.
  4. Add images and media, following the guidelines.
  5. Use links and references, adhering to the documentation.
  6. Add code samples, following the guidelines.
  7. Review the docs, building them locally to check for errors.

Documentation Style Guide

Refer to the documentation style guide for guidance on writing and organizing the docs.

Sources