# Getting Started

Welcome to **mp-units**! This guide will help you navigate the documentation and find exactly
what you need, whether you're new to the library or an experienced user looking for specific
information.

## New to mp-units?

If you're encountering **mp-units** for the first time, start by exploring the **Getting Started**
section. Here you'll find essential information to get up and running:

- What the library is and its key features
- Compiler compatibility and system requirements
- Installation and build system integration
- Quick introduction to core concepts
- The library's syntax and style
- Compile-time safety features

**Once you're set up and familiar with the basics,** explore the sections below to continue
your learning journey.

## How Our Documentation Is Organized

The **mp-units** documentation is designed to support different ways of learning and working.
Choose the section that matches what you need right now:

=== "Tutorials"

    **[Tutorials](../tutorials/index.md)** are **learning-oriented** lessons that teach by doing.
    They assume no prior knowledge and build your confidence progressively through hands-on examples.

    **When to use:** You're learning **mp-units** for the first time or want to master a specific
    feature through guided lessons.

    **Best for:** Beginners, systematic learning, building confidence through practice.

=== "User's Guide"

    The **[User's Guide](../users_guide/index.md)** provides **explanation-oriented** documentation
    covering all library concepts in depth. Read it like a book to build a complete mental model,
    or jump to specific chapters when you need thorough understanding of particular topics.

    **When to use:** You want deep understanding of how and why things work the way they do.

    **Best for:** Gaining mastery, designing complex systems, understanding rationale.

=== "Workshops"

    **[Workshops](../workshops/index.md)** combine learning with practice through exercise-driven
    code with TODO markers. They bridge tutorials and production code, helping you master advanced
    patterns through doing.

    **When to use:** You want hands-on practice with advanced patterns and real-world scenarios.

    **Best for:** Moving beyond basics, learning by doing, refactoring existing code.

=== "How-to Guides"

    **[How-to Guides](../how_to_guides/index.md)** are **task-oriented** instructions focused on
    getting things done. They assume you know the basics and need practical steps for specific
    scenarios like integration, migration, or advanced techniques.

    **When to use:** You have a specific task to accomplish or problem to solve.

    **Best for:** Integration challenges, migration tasks, achieving specific goals.

=== "Examples"

    **[Examples](../examples/index.md)** demonstrate the library in action with full, runnable
    programs ranging from simple introductions to complex domain-specific applications. Study them
    to understand how features work together or adapt them for your own projects.

    **When to use:** You want to see complete, working code in realistic scenarios.

    **Best for:** Understanding real-world usage, finding patterns to adapt, seeing the big picture.

=== "Reference"

    The **[Reference](../reference/index.md)** provides **information-oriented** technical
    descriptions including API details, available systems, quantities, units, and a comprehensive
    cheat sheet.

    **When to use:** You need precise technical information about specific library features.

    **Best for:** Looking up syntax, finding available units, checking API details.

## Quick Decision Tree

**Choose your path based on your situation:**

- 🆕 **"I'm completely new to mp-units"**  
  → Explore [Quick Start](quick_start.md) and [Look and Feel](look_and_feel.md) to see what
  the library offers, check the [Cheat Sheet](../reference/cheat_sheet.md) for quick reference

- 🚀 **"I want to use it in my project"**  
  → Check [Compiler Support](cpp_compiler_support.md), follow
  [Installation](installation_and_usage.md), then start with [Tutorials](../tutorials/index.md)

- 📚 **"I learn best by following structured lessons"**  
  → Go to [Tutorials](../tutorials/index.md)

- 🎓 **"I want to understand the concepts deeply"**  
  → Read the [User's Guide](../users_guide/index.md)

- 💪 **"I want to practice with realistic exercises"**  
  → Try the [Workshops](../workshops/index.md)

- 🎯 **"I need to solve a specific problem"**  
  → Check [How-to Guides](../how_to_guides/index.md)

- 💡 **"Show me working examples"**  
  → Browse [Examples](../examples/index.md)

- 🔍 **"I need to look up technical details"**  
  → Search the [Reference](../reference/index.md)

## Getting Help

- **Questions?** Check the [FAQ](faq.md)
- **Found a bug?** [Report it on GitHub](https://github.com/mpusz/mp-units/issues)
- **Need discussion?** Join [GitHub Discussions](https://github.com/mpusz/mp-units/discussions)
- **Want to contribute?** See [Contributing](contributing.md)

---

!!! tip "Documentation Framework"

    This documentation follows the [Diátaxis framework](https://diataxis.fr/), a systematic
    approach to technical documentation that recognizes different modes of learning and working.
    Each section serves a distinct purpose to help you succeed at different stages of your
    journey with **mp-units**.