Overview

This documentation is intended to remove ambiguity in MyMaxwell portal development. It should be a common reference for making development decisions affecting user interface, performance, reports generation, infrastructure cost, roles’ privileges.

Intended users

• HTMS CEO - Tom Grizetti
• HTMS development lead - Marco Potenza
• Developers
• Designers
• Sprinterra management
• DevOps team
• Outside consultants
• And most importantly - QA engineer

Documentation workflow

Each call, email chain or personal discussion resulting into decision making should be reflected in the documentation at least in the form of meeting minutes, ideally as a decision page. This will make it easier to refence taken decisions removing “He said that on the call from XX October last year”.

Source location

All sources are stored in a git repository located at https://bitbucket.org/sprinterra/htms-docs. All new editors should get a bitbucket account in order to make changes. Ask Sprinterra devops.

View access

Currently view access is respricted on IP address basis. Ask Sprinterra devops to add new IP.

How to use it

The documentation is written in Markdown and compiled into a static website using mdBook. This README provides instructions for developers, users, and DevOps on how to:

• Run the documentation locally for preview and editing
• Build the documentation for deployment

Prerequisites

• Rust (recommended) or
• Install mdBook directly via other package managers (see mdBook installation)

Running mdBook Locally

To preview the documentation locally while you work on it:

1. Clone the repository

   git clone <repository-url>
   cd <repository-folder>
   

2. Run the mdBook server

This command starts a local web server with live reload.

mdbook serve

3. Open your browser

Visit http://localhost:3000/ to see the documentation.

4. Edit the markdown files

Changes will automatically refresh in the browser.

Building for Deployment

To generate the static files for deployment (e.g., to a web server, S3 bucket, or any static site hosting):

1. Build the book

   mdbook build
   

2. Output directory

The static website files will be generated inside the book/ directory by default.

3. Deploy

Copy the contents of the book/ directory to your deployment target.

Why mdbook

mdbook documentation engine was chosen because it is:

• lightweight and super fast to navigate
• static and portable
• every change is easily trackable via git
• textual math formulas and diagram thanks to Mathjax and Mermaid

timeline
    title Test timeline diagram
    2002 : LinkedIn
    2004 : Facebook
         : Google
    2005 : YouTube
    2006 : Twitter