FlexMeasures · nhoening · Mar 19, 2021 · Mar 11, 2021 · Mar 11, 2021 · Mar 11, 2021
diff --git a/documentation/changelog.rst b/documentation/changelog.rst
@@ -8,9 +8,11 @@ v0.2.4 | March XX, 2021
 
 Bugfixes
 --------
+* Show screenshots in documentation and add some missing content [see `PR #60 <http://www.github.com/SeitaBV/flexmeasures/pull/60>`_]
 * Documentation listed 2.0 API endpoints twice [see `PR #59 <http://www.github.com/SeitaBV/flexmeasures/pull/59>`_]
 
 
+
 v0.2.3 | February 27, 2021
 ===========================
 

diff --git a/documentation/img/components.png b/documentation/img/components.png
diff --git a/documentation/img/legend.png b/documentation/img/legend.png
diff --git a/documentation/index.rst b/documentation/index.rst
@@ -38,12 +38,11 @@ The platform operator of FlexMeasures can be an Aggregator.
    changelog
 
 .. toctree::
-    :caption: The pages
+    :caption: The in-built UI
     :maxdepth: 1
 
     views/dashboard
     views/portfolio
-    views/control
     views/analytics
     views/admin
 
@@ -59,7 +58,7 @@ The platform operator of FlexMeasures can be an Aggregator.
 
 
 .. toctree::
-    :caption: API Documentation
+    :caption: The API 
     :maxdepth: 1
 
     api/introduction
@@ -86,7 +85,6 @@ The platform operator of FlexMeasures can be an Aggregator.
     qa/users
     qa/assets
     qa/markets
-    qa/components
     qa/algorithms
     qa/data
 

diff --git a/documentation/qa/assets.rst b/documentation/qa/assets.rst
@@ -34,6 +34,7 @@ Defaults:
 - Mode: consumer
 - Periodicity: none
 
+
 Electric Vehicle Supply Equipment (EVSE)
 --------------------------------------------------------
 

diff --git a/documentation/qa/components.rst b/documentation/qa/components.rst
diff --git a/documentation/views/admin.rst b/documentation/views/admin.rst
@@ -9,10 +9,31 @@ The administrator can edit assets and user accounts here.
 Assets
 ------
 
-Edit meta data
+Listing all assets:
+
+.. image:: https://github.com/SeitaBV/screenshots/raw/main/screenshot_assets.png
+    :align: center
+..    :scale: 40%
+
+Viewing & editing one asset:
+
+.. image:: https://github.com/SeitaBV/screenshots/raw/main/screenshot_asset.png
+    :align: center
+..    :scale: 40%
 
 
 Users
 -----
 
-None yet.
+Listing all users:
+
+.. image:: https://github.com/SeitaBV/screenshots/raw/main/screenshot_users.png
+    :align: center
+..    :scale: 40%
+
+
+Viewing one user:
+
+.. image:: https://github.com/SeitaBV/screenshots/raw/main/screenshot_user.png
+    :align: center
+..    :scale: 40%
diff --git a/documentation/views/analytics.rst b/documentation/views/analytics.rst
@@ -5,40 +5,50 @@ Client analytics
 ****************
 
 The client analytics page shows relevant data to an asset's operation: production and consumption, market prices and weather data.
-The view serves to browse through available data and to assess how the app is monitoring and forecasting data streams from various sources.
+The view serves to browse through available data history and to assess how the app is monitoring and forecasting data streams from various sources.
 In particular, the page contains:
 
 .. contents::
     :local:
     :depth: 1
 
 
+.. image:: https://github.com/SeitaBV/screenshots/raw/main/screenshot_analytics.png
+    :align: center
+..    :scale: 40%
+
+
 .. _analytics_controls:
 
-Data browsing
+Data filtering
 =============
 
-...
+FlexMeasures offers data analytics on various aggregation levels: per asset, per asset type or even per higher aggregation levels like all renewables.
+
+The time window is freely selectable.
+
+In addition, the source of market and weather data can be selected, as well as the forecast horizon.
+
+For certain assets, which bundle meters on the same location, individual traces can be shown next to each other in the (upper left) power plot, for comparison.
 
 
 .. _analytics_plots:
 
 Data visualisation
 ==================
 
-...
+In each plot, the data is shown for different types of data: measurements (e.g. of power or prices), forecasts and schedules (only for power, obviously).
+
+In the FlexMeasures platform, forecasting models can indicate a range of uncertainty around their forecasts, which will also be shown in plots if available. 
 
 
 .. _analytics_metrics:
 
-Statistics
+Metrics
 ==========
 
-...
-
+FlexMeasures summarises the visualised data as realised (by measurement) and expected (by forecast) sums.
+In addition, the mean average error (MAE) and the weighted absolute percentage error (WAPE) are computed for power,
+weather and price data if forecasts are available for the chosen time range.
 
-.. image:: ../img/screenshot_analytics.png
-    :target: ../../../../../../analytics
-    :align: center
-..    :scale: 40%
 
diff --git a/documentation/views/control.rst b/documentation/views/control.rst
@@ -1,34 +1,33 @@
 .. _control:
 
 *****************
-Flexibility actions
+Flexibility opportunities
 *****************
 
-Flexibility actions have commercial value that users can valorise on.
-In the Flexibility actions page, FlexMeasures shows all flexibility actions that the user can take for a selected time window.
-When FlexMeasures has identified commercial value for flexibility actions, the user is suggested to order them.
-The user can opt to automate this otherwise manual process.
-Listed flexibility actions include previously ordered actions and currently offered actions.
-Currently offered actions are presented as an order book, where they are sorted according to their commercial value.
-The user can place orders and check the expected value of offers.
+Flexibility opportunities have commercial value that users can valorise on.
+When FlexMeasures has identified commercial value for flexibility opportunities, the user is suggested to act on them.
+This might happen manually (operators seeing opportunities in the FlexMeasures UI) or in an automated fashion
+(scripts reading out suggested flexible schedules from the FlexMeasures API and implementing them to local operations if possible).
+
+In the Flexibility opportunities page (a yet-to-be designed feature discussed below), FlexMeasures shows all flexibility opportunities that the user can take for a selected time window.
 
 .. contents::
     :local:
     :depth: 1
 
 
-.. _action_types:
+.. _opportunity_types:
 
-Types of flexibility actions
+Types of flexibility opportunities
 ==========================
 
-The platform distinguishes between different types of flexibility actions that an asset can take.
+The platform distinguishes between different types of flexibility opportunities and the type of action to take advantage of it.
 
 Curtailment
 -----------
 
 Curtailment happens when an asset temporarily lowers or stops its production or consumption.
-A defining feature of curtailment is that total production or consumption at the end of the flexibility action has decreased.
+A defining feature of curtailment is that total production or consumption at the end of the flexibility opportunity has decreased.
 
 - A typical example of curtailing production is when a wind turbine adjusts the pitch angle of its blades to decrease the generator torque.
 - An example of curtailing consumption is load shedding of energy intensive industries.
@@ -46,7 +45,7 @@ Shifting
 --------
 
 Shifting happens when an asset delays or advances its energy production or consumption.
-A defining feature of shifting is that total production or consumption at the end of the flexibility action remains the same.
+A defining feature of shifting is that total production or consumption at the end of the flexibility opportunity remains the same.
 
 - An example of delaying consumption is when a charging station postpones the charging process of an electric vehicle.
 - An example of advancing consumption is when a cooling unit starts to cool before the upper temperature bound was reached (pre-cooling).
@@ -58,15 +57,24 @@ The net effect of a shifting action is measured in terms of an energy-time volum
 This volume is a multiplication of the energy volume being shifted and the duration of that shift.
 
 
-Visualisation of actions
+Visualisation of opportunities
 ========================
 
-Flexibility actions cause changes to the power profile of an asset.
-Depending on the time window selection and constraints set by the asset owner, the effects of an action may partially take place outside of the selected time window.
-Such effects are taken into account by FlexMeasures and shown to the user, e.g. as a part of expected value calculations and power profile forecasts.
+Visualising flexibility opportunities and their effects is not straightforward.
 
+Here is a potential UX design which we have not implemented yet:
 
-.. image:: ../img/screenshot_control.png
-    :target: ../../../../../../control
+.. image:: https://github.com/SeitaBV/screenshots/raw/main/screenshot_control.png
     :align: center
 ..    :scale: 40%
+
+Flexibility opportunities cause changes to the power profile of an asset.
+Such effects could be taken into account by FlexMeasures and shown to the user, e.g. as a part of expected value calculations and power profile forecasts.
+
+An example how this could look like is below.
+The operator can select flexibility opportunities which have a value attached to them and see the effects on the power profile in a visual manner.
+
+Listed flexibility opportunities include previously realised opportunities and currently offered opportunities.
+Currently offered opportunties are presented as an order book, where they are sorted according to their commercial value.
+
+Of course, depending on the time window selection and constraints set by the asset owner, the effects of an opportunity may partially take place outside of the selected time window.
diff --git a/documentation/views/dashboard.rst b/documentation/views/dashboard.rst
@@ -5,32 +5,34 @@ Dashboard
 *********
 
 The dashboard shows where the user's assets are located and how many different asset types are connected to the platform.
-The view serves to quickly identify the status of assets, such as whether they are taking part in any flexibility actions or whether there are upcoming opportunities to valorise on flexibility actions.
+The view serves to quickly identify the status of assets, such as whether there are upcoming opportunities to valorise on flexibility actions.
 In particular, the page contains:
 
 .. contents::
     :local:
     :depth: 1
 
 
+.. image:: https://github.com/SeitaBV/screenshots/raw/main/screenshot_dashboard.png
+    :align: center
+..    :scale: 40%
+
+
 .. _dashboard_map:
 
 Interactive map of assets
 =========================
 
-The map shows all of the user's assets, using color codes to indicate whether the platform has identified upcoming flexibility opportunities.
-Clicking on an asset allows the user to navigate to the :ref:`control` page to verify the offered flexibility action and to possibly order the action.
+The map shows all of the user's assets with icons for each asset type.
+Clicking on an asset allows the user to see its current state (e.g. latest measurement of wind power production) and to navigate to the :ref:`analaytics` page
+to see more details, for instance forecasts.
 
 
 .. _dashboard_summary:
 
 Summary of asset types
 ======================
 
-The summary below the map lists all asset types that the user has hooked up to the platform.
+The summary below the map lists all asset types that the user has hooked up to the platform and how many of each there are.
+Clicking on the asset type name leads to the :ref:`analaytics` page, where data is shown aggregated for that asset type. 
 
-
-.. image:: ../img/screenshot_dashboard.png
-    :target: ../../../../../../dashboard
-    :align: center
-..    :scale: 40%