flixOpt · FBumann · Oct 30, 2025 · Oct 29, 2025 · Oct 29, 2025 · Oct 29, 2025
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -81,6 +81,8 @@ If upgrading from v2.x, see the [v3.0.0 release notes](https://github.com/flixOp
 ### 📦 Dependencies
 
 ### 📝 Docs
+- Add more comprehensive `CONTRIBUTE.md`
+- Improve logical structure in User Guide
 
 ### 👷 Development
 

diff --git a/CONTRIBUTE.md b/CONTRIBUTE.md
@@ -0,0 +1,135 @@
+# Contributing to FlixOpt
+
+We warmly welcome contributions from the community! Whether you're fixing bugs, adding features, improving documentation, or sharing examples, your contributions are valuable.
+
+## Ways to Contribute
+
+### 🐛 Report Issues
+Found a bug or have a feature request? Please [open an issue](https://github.com/flixOpt/flixopt/issues) on GitHub.
+
+When reporting issues, please include:
+- A clear description of the problem
+- Steps to reproduce the issue
+- Expected vs. actual behavior
+- Your environment (OS, Python version, FlixOpt version)
+- Minimal code example if applicable
+
+### 💡 Share Examples
+Help others learn FlixOpt by contributing examples:
+- Real-world use cases
+- Tutorial notebooks
+- Integration examples with other tools
+- Add them to the `examples/` directory
+
+### 📖 Improve Documentation
+Documentation improvements are always welcome:
+- Fix typos or clarify existing docs
+- Add missing documentation
+- Translate documentation
+- Improve code comments
+
+### 🔧 Submit Code Contributions
+Ready to contribute code? Great! See the sections below for setup and guidelines.
+
+---
+
+## Development Setup
+
+### Getting Started
+1. Fork and clone the repository:
+   ```bash
+   git clone https://github.com/flixOpt/flixopt.git
+   cd flixopt
+   ```
+
+2. Install development dependencies:
+   ```bash
+   pip install -e ".[full, dev]"
+   ```
+
+3. Set up pre-commit hooks (one-time setup):
+   ```bash
+   pre-commit install
+   ```
+
+4. Verify your setup:
+   ```bash
+   pytest
+   ```
+
+### Working with Documentation
+FlixOpt uses [mkdocs](https://www.mkdocs.org/) to generate documentation.
+
+To work on documentation:
+```bash
+pip install -e ".[docs]"
+mkdocs serve
+```
+Then navigate to http://127.0.0.1:8000/
+
+---
+
+## Code Quality Standards
+
+### Automated Checks
+We use [Ruff](https://github.com/astral-sh/ruff) for linting and formatting. After the one-time setup above, **code quality checks run automatically on every commit**.
+
+### Manual Checks
+To run checks manually:
+- `ruff check --fix .` - Check and fix linting issues
+- `ruff format .` - Format code
+- `pre-commit run --all-files` - Run all pre-commit checks
+
+### Testing
+- `pytest` - Run the test suite
+- Ensure all tests pass before submitting a PR
+
+### Coding Guidelines
+- Follow [PEP 8](https://pep8.org/) style guidelines
+- Write clear, self-documenting code with helpful comments
+- Include type hints for function signatures
+- Create or update tests for new functionality
+- Aim for 100% test coverage for new code
+
+---
+
+## Workflow
+
+### Branches & Pull Requests
+1. Create a feature branch from `main`:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. Make your changes and commit them with clear messages
+
+3. Push your branch and open a Pull Request
+
+4. Ensure all CI checks pass
+
+### Branch Naming
+- Features: `feature/feature-name`
+- Bug fixes: `fix/bug-description`
+- Documentation: `docs/what-changed`
+
+### Commit Messages
+- Use clear, descriptive commit messages
+- Start with a verb (Add, Fix, Update, Remove, etc.)
+- Keep the first line under 72 characters
+
+---
+
+## Releases
+
+We follow **Semantic Versioning** (MAJOR.MINOR.PATCH). Releases are created manually from the `main` branch by maintainers.
+
+---
+
+## Questions?
+
+If you have questions or need help, feel free to:
+- Open a discussion on GitHub
+- Ask in an issue
+- Reach out to the maintainers
+
+Thank you for contributing to FlixOpt!
diff --git a/docs/contribute.md b/docs/contribute.md
@@ -1,45 +1 @@
-# Contributing to the Project
-
-We warmly welcome contributions from the community! This guide will help you get started with contributing to our project.
-
-## Development Setup
-1. Clone the repository `git clone https://github.com/flixOpt/flixopt.git`
-2. Install the development dependencies `pip install -e ".[dev]"`
-3. Install pre-commit hooks `pre-commit install` (one-time setup)
-4. Run `pytest` to ensure your code passes all tests
-
-## Code Quality
-We use [Ruff](https://github.com/astral-sh/ruff) for linting and formatting. After the one-time setup above, **code quality checks run automatically on every commit**.
-
-To run manually:
-- `ruff check --fix .` to check and fix linting issues
-- `ruff format .` to format code or
-- `pre-commit run` or `pre-commit run --all-files` to trigger all checks
-
-## Documentation (Optional)
-FlixOpt uses [mkdocs](https://www.mkdocs.org/) to generate documentation.
-To work on documentation:
-```bash
-pip install -e ".[docs]"
-mkdocs serve
-```
-Then navigate to http://127.0.0.1:8000/
-
-## Testing
-- `pytest` to run the test suite
-- You can also run the provided python script `run_all_test.py`
-
----
-# Best practices
-
-## Coding Guidelines
-
-- Follow PEP 8 style guidelines
-- Write clear, commented code
-- Include type hints
-- Create or update tests for new functionality
-- Ensure 100% test coverage for new code
-
-## Branches & Releases
-New features should be branched from `main` into `feature/*`
-As stated, we follow **Semantic Versioning**. Releases are created manually from the `main` branch.
+{! ../CONTRIBUTE.md !}
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -37,6 +37,6 @@ Working with FlixOpt follows a general pattern:
 
 Now that you've installed FlixOpt and understand the basic workflow, you can:
 
-- Learn about the [core concepts of FlixOpt](user-guide/index.md)
+- Learn about the [core concepts of flixopt](user-guide/core-concepts.md)
 - Explore some [examples](examples/index.md)
 - Check the [API reference](api-reference/index.md) for detailed documentation
diff --git a/docs/index.md b/docs/index.md
@@ -139,6 +139,6 @@ Help improve FlixOpt by contributing code, docs, or examples
 
 {%
    include-markdown "../README.md"
-   start="## Installation"
-   end="## License"
+   start="## 🛠️ Installation"
+   end="## 📄 License"
 %}
diff --git a/docs/user-guide/index.md → docs/user-guide/core-concepts.md b/docs/user-guide/index.md → docs/user-guide/core-concepts.md
@@ -1,10 +1,10 @@
-# FlixOpt Concepts
+# Core concepts of flixopt
 
 FlixOpt is built around a set of core concepts that work together to represent and optimize **any system involving flows and conversions** - whether that's energy systems, material flows, supply chains, water networks, or production processes.
 
 This page provides a high-level overview of these concepts and how they interact.
 
-## Core Concepts
+## Main building blocks
 
 ### FlowSystem
 
@@ -121,19 +121,20 @@ This [`CalculationResults`][flixopt.results.CalculationResults] object can be sa
 The process of working with FlixOpt can be divided into 3 steps:
 
 1. Create a [`FlowSystem`][flixopt.flow_system.FlowSystem], containing all the elements and data of your system
-     -  Define the time series of your system
-     -  Add [`Components`][flixopt.components] like [`Boilers`][flixopt.linear_converters.Boiler], [`HeatPumps`][flixopt.linear_converters.HeatPump], [`CHPs`][flixopt.linear_converters.CHP], etc.
-     -  Add [`Buses`][flixopt.elements.Bus] as connection points in your system
+     -  Define the time horizon of your system (and optionally your periods and scenarios, see [Dimensions](mathematical-notation/dimensions.md)))
      -  Add [`Effects`][flixopt.effects.Effect] to represent costs, emissions, etc.
-     - *This [`FlowSystem`][flixopt.flow_system.FlowSystem] can also be loaded from a netCDF file*
+     -  Add [`Buses`][flixopt.elements.Bus] as connection points in your systeand [`Sinks`][flixopt.components.Sink] & [`Sources`][flixopt.components.Source] as connections to the outer world (markets, power grid, ...)
-     -  Add [`Buses`][flixopt.elements.Bus] as connection points in your systeand [`Sinks`][flixopt.components.Sink] & [`Sources`][flixopt.components.Source] as connections to the outer world (markets, power grid, ...)
+     -  Add [`Buses`][flixopt.elements.Bus] as connection points in your system and [`Sinks`][flixopt.components.Sink] & [`Sources`][flixopt.components.Source] as connections to the outer world (markets, power grid, ...)
-     -  Add [`Buses`][flixopt.elements.Bus] as connection points in your systeand [`Sinks`][flixopt.components.Sink] & [`Sources`][flixopt.components.Source] as connections to the outer world (markets, power grid, ...)
+     -  Add [`Buses`][flixopt.elements.Bus] as connection points in your system and [`Sinks`][flixopt.components.Sink] & [`Sources`][flixopt.components.Source] as connections to the outer world (markets, power grid, ...)
+     -  Add [`Components`][flixopt.components] like [`Boilers`][flixopt.linear_converters.Boiler], [`HeatPumps`][flixopt.linear_converters.HeatPump], [`CHPs`][flixopt.linear_converters.CHP], etc.
+     -  Add
+     - [`FlowSystems`][flixopt.flow_system.FlowSystem] can also be loaded from a netCDF file*
 2. Translate the model to a mathematical optimization problem
      - Create a [`Calculation`][flixopt.calculation.Calculation] from your FlowSystem and choose a Solver
-     - ...The Calculation is translated internaly to a mathematical optimization problem...
+     - ...The Calculation is translated internally to a mathematical optimization problem...
      - ...and solved by the chosen solver.
 3. Analyze the results
      - The results are stored in a [`CalculationResults`][flixopt.results.CalculationResults] object
      - This object can be saved to file and reloaded from file, retaining all information about the calculation
-     - As it contains the used [`FlowSystem`][flixopt.flow_system.FlowSystem], it can be used to start a new calculation
+     - As it contains the used [`FlowSystem`][flixopt.flow_system.FlowSystem], it fully documents all assumptions taken to create the results.
 
 <figure markdown>
   ![FlixOpt Conceptual Usage](../images/architecture_flixOpt.png)

diff --git a/docs/user-guide/mathematical-notation/index.md b/docs/user-guide/mathematical-notation/index.md
@@ -1,9 +1,9 @@
 
 # Mathematical Notation
 
-This section provides the **mathematical formulations** underlying FlixOpt's optimization models. It is intended as **reference documentation** for users who want to understand the mathematical details behind the high-level FlixOpt API described in the [FlixOpt Concepts](../index.md) guide.
+This section provides the **mathematical formulations** underlying FlixOpt's optimization models. It is intended as **reference documentation** for users who want to understand the mathematical details behind the high-level FlixOpt API described in the [FlixOpt Concepts](../core-concepts.md) guide.
 
-**For typical usage**, refer to the [FlixOpt Concepts](../index.md) guide, [Examples](../../examples/index.md), and [API Reference](../../api-reference/index.md) - you don't need to understand these mathematical formulations to use FlixOpt effectively.
+**For typical usage**, refer to the [FlixOpt Concepts](../core-concepts.md) guide, [Examples](../../examples/index.md), and [API Reference](../../api-reference/index.md) - you don't need to understand these mathematical formulations to use FlixOpt effectively.
 
 ---
 

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -11,9 +11,9 @@ repo_name: flixOpt/flixopt
 nav:
   - Home: index.md
   - User Guide:
-    - user-guide/index.md
-    - Migration to v3.0.0: user-guide/migration-guide-v3.md
     - Getting Started: getting-started.md
+    - Core Concepts: user-guide/core-concepts.md
+    - Migration to v3.0.0: user-guide/migration-guide-v3.md
     - Mathematical Notation:
       - Overview: user-guide/mathematical-notation/index.md
       - Dimensions: user-guide/mathematical-notation/dimensions.md

diff --git a/tests/run_all_tests.py b/tests/run_all_tests.py