ATLAS Documentation Portal

Deploy Link

Setup

Install Visual Studio Code.

Install Python 3.7 or later, which should come with pip.

From the project directory, it is recommended to first create a virtual environment:

python -m venv .venv

Then install dependencies:

pip install -r requirements.txt

Preview the docs in a local web browser as follows:

mkdocs serve

On windows machine, do:

python -m mkdocs serve --livereload

Contribution Guidelines

As part of the new structure the following guidelines should be considered when adding or amending any of the documentation.

User Guides

This guide outlines the structure, content expectation and best practices for contributing to the User Guide section of the ATLAS documentation site. It's designed to provide a consistent structure for quick understanding of the ATLAS eco-system and product suite for a non-technical user.

You Audience

• Prospect wanting to find out about ATLAS's capabilities
• Current customer wanting to find out about the entire ATLAS eco-system and how other product offerings can be utilised to achieve specific goals
• Current user wanting to find out about how to perform a specific action, or get help with any of the ATLAS products

User guides can be found under Key Functionality heading. At the moment this is the structure, intended to allow the user to follow data through the ATLAS ecosystem:

• Configuration: System Monitor
• Store and Distribute: SQL Race, SRMS, ADS, RDS
• Process: SECU, vTAG Server, MCT Toolbox
• Visualise: ATLAS

Note: Some of these sections do not exist currently as we migrate existing documentation to this site.

When creating content under Key Functionality:

• Writing for Main Users.
• This includes overviews of the main products being offered.
• This should be heavy on screenshots / video tutorials as they're easier to follow and digest
• Each new product should fit somewhere in the data pipeline, and should get its own area.

What's the difference between Key Functionality and Extending ATLAS?

Extending ATLAS is intended for explaining architectural solutions. At the moment we have SECU and RTA. When contributing to Extending ATLAS:

• Writing for a mix, this is mainly for decision makers of systems
• This is high level architecture discussions
• Filled with best practises and recommendations of usage
• This should have architectural or system diagrams to help readers understand the overall structure.

Note: If we have not fully released a solution, we should put a disclaimer at the top that content can change depending on feedback and roadmap changes (see RTA guide for an example of this).

Developer Resources

This guide outlines the structure, content expectations, and best practices for contributing to the Developer Documentation for any product. It is designed to ensure consistency, clarity, and ease of use for developers integrating with our systems.

Your Audience

• Technical wanting to build on-top of the off the shelf ecosystem
• Using APIs and SDK wants resources to be immediately available to them with clear structured documentation and examples.
• Is not particularly interested in the pros and cons - is likely already convinced and is trying to figure out how to actually solve their problems.

Each product should following the following structure:

/<ProductName>
│
├── API_1_Name/
│   ├── overview.md
│   ├── integration-guide.md
│   ├── reference.md
│   │       ├── Methods
│   │       ├── Endpoints
│   │       ├── Commands
│   ├── examples.md
│   ├── troubleshooting.md
│   └── best-practices.md
│
├── API_N_Name/
│   └── ...

Descriptions of pages:

• overview.md: What this interface is for and when to use it.
• integration-guide.md: Step-by-step instructions for integrating this interface. Setup etc.
• reference.md: Complete technical reference for all operations.

# Reference Example Structure

## Overview
- **Interface type**: REST / SDK / CLI / etc.
- **Version**: v1.0
- **Base URL / Entry Point**: `https://api.example.com/v1/`
- **Authentication**: API key / OAuth2 / etc.
- **Error Handling**: Common error codes and retry logic

---

## Operations

### <Operation Name> (e.g. `GetTelemetryData`)
- **Description**: What this does and when to use it.
- **Method**: `GET` / `POST` / `CALL` / `COMMAND`
- **Endpoint / Signature**: `/telemetry/data` or `GetTelemetryData(params)`
- **Parameters**:
  | Name       | Type     | Required | Description                  |
  |------------|----------|----------|------------------------------|
  | `startTime`| `string` | Yes      | ISO 8601 timestamp           |
- **Response**:
  ```json
  {
    "data": [...],
    "nextPageToken": "abc123"
  }
  ```
- **Errors**:
  | Code       | Message     | Meaning | 
  |------------|----------|----------|
  | `401`| `Unauthorized` | Invalid or missing token      |  
- **Examples**:
    ```
    curl -X GET "https://api.example.com/v1/telemetry/data?startTime=..." \
        -H "Authorization: Bearer <token>"
    ```

• examples.md: Real-world usage examples, walkthrough sample codes.
• troubleshooting.md: Known issues and how to resolve them.
• best-practices.md: Performance tips, security considerations, maintainability.

Writing guidelines

• Use clear, concise language.
• Prefer code examples over prose.
• Use headings and tables for readability.
• Keep one concept per file.
• Use relative links to connect sections.

Checklist Before PR

• All required files are present.
• Code examples are tested and accurate.
• Markdown is linted and renders correctly.
• File names and headings follow naming conventions.