Improve README pages

README.md

@@ -10,6 +10,11 @@
 
 # MUSE2
 
+## Overview
+
+> :warning: **Please note that MUSE2 currently only works with simple models and is not yet suitable
+for use in research.** :warning:
+
 MUSE2 (**M**od**U**lar energy systems **S**imulation **E**nvironment) is a tool for running
 simulations of energy systems, written in Rust. Its purpose is to provide users with a framework to
 simulate pathways of energy system transition, usually in the context of climate change mitigation.
@@ -18,15 +23,15 @@ It is the successor to [MUSE], which is written in Python. It was developed foll
 MUSE to address a range of legacy issues that are challenging to address via upgrades to the
 existing MUSE framework, and to implement the framework in the high-performance Rust language.
 
-Please note that MUSE2 currently only works with simple models and is not yet suitable for use in
-research.
+[MUSE]: https://github.com/EnergySystemsModellingLab/MUSE_OS
 
-To download the latest version of MUSE2 for your platform, please visit [the releases page].
+## Getting started
 
-[MUSE]: https://github.com/EnergySystemsModellingLab/MUSE_OS
-[the releases page]: https://github.com/EnergySystemsModellingLab/MUSE2/releases
+For information on getting started with MUSE2, please consult [the documentation].
+
+[the documentation]: https://energysystemsmodellinglab.github.io/MUSE2/
 
-## Model Overview
+## Description of model
 
 MUSE is an [Integrated Assessment Modelling] framework that is designed to enable users to create
 and apply an agent-based model to simulate a market equilibrium on a set of user-defined
@@ -45,21 +50,6 @@ foresight over the whole modelled time horizon.
 [TIMES]: https://iea-etsap.org/index.php/etsap-tools/model-generators/times
 [MESSAGEix]: https://docs.messageix.org/en/latest
 
-## Getting started
-
-The easiest way to install MUSE2 is to download the latest version for your platform on [our
-releases page]. For information on getting started, please consult [the documentation].
-
-If you wish to develop MUSE2 or build it from source, please see [the developer guide].
-
-You can also install the [`muse2` crate from crates.io][muse2-crate], though this installation
-method is only recommended for developers.
-
-[our releases page]: https://github.com/EnergySystemsModellingLab/MUSE2/releases
-[the documentation]: https://energysystemsmodellinglab.github.io/MUSE2/
-[the developer guide]: https://energysystemsmodellinglab.github.io/MUSE2/developer_guide/
-[muse2-crate]: https://crates.io/crates/muse2
-
 ## Citing this repository
 
 If you use MUSE2 in your work, please cite us. For information on how to cite this repository, see

docs/README.md

@@ -1,18 +1,42 @@
-# Introduction
+# MUSE2
 
-MUSE2 is a tool for running simulations of energy systems, written in Rust. It is a slimmer and
-faster version of [the older MUSE tool]. To get started, please look at the [user guide]
-and the [command line help].
+## Overview
 
-For an overview of the model, see the [model description] and the [dispatch optimisation
-formulation]. For a list of relevant terms, see the [glossary].
+> ⚠️ **Please note that MUSE2 currently only works with simple models and is not yet suitable
+for use in research.** ⚠️
 
-If you are a developer, please see the [developer guide].
+MUSE2 (**M**od**U**lar energy systems **S**imulation **E**nvironment) is a tool for running
+simulations of energy systems, written in Rust. Its purpose is to provide users with a framework to
+simulate pathways of energy system transition, usually in the context of climate change mitigation.
 
-[the older MUSE tool]: https://github.com/EnergySystemsModellingLab/MUSE_OS
+It is the successor to [MUSE], which is written in Python. It was developed following re-design of
+MUSE to address a range of legacy issues that are challenging to address via upgrades to the
+existing MUSE framework, and to implement the framework in the high-performance Rust language.
+
+[MUSE]: https://github.com/EnergySystemsModellingLab/MUSE_OS
+
+## Getting started
+
+You will first need to install MUSE2. We recommend downloading the latest version for your platform
+on [the releases page]. The archive file you download should contain a readme file containing
+instructions on how to run MUSE2. Alternatively, you can install the [`muse2` crate from
+crates.io][muse2-crate] using [`cargo`] (see [Setting up your development environment][dev-setup]).
+
+Once you have installed MUSE2, you can look at the [user guide] and the [command line help] for
+details on how to get started with creating and running your own models.
+
+Detailed information about the model used by MUSE2 is provided in [Model Description]. For a list of
+relevant terms, see the [glossary].
+
+If you want to work with the MUSE2 source code, for instance to submit a change to this repository,
+please see the [developer guide].
+
+[the releases page]: https://github.com/EnergySystemsModellingLab/MUSE2/releases
+[`cargo`]: https://doc.rust-lang.org/cargo/
+[dev-setup]: ./developer_guide/setup.md
+[muse2-crate]: https://crates.io/crates/muse2
 [user guide]: ./user_guide.md
 [command line help]: ./command_line_help.md
-[model description]: ./model/
-[dispatch optimisation formulation]: ./model/dispatch_optimisation.md
+[Model Description]: ./model/
 [glossary]: ./glossary.md
 [developer guide]: ./developer_guide/