Documentation Ideas

[victorgarcia98]

Documentation is one of the most important things of FlexMeasures as we are dealing with complex problems that involve a lot of concepts.

To spread the word of FlexMeasures even further, we need to improve the documentation, giving the Scheduling feature a more important space.

For that, I went through the documentation trying to ask myself which question I would made If I visited the docs the first time. These are some of the questions that came up first:

• How does it look? How can I interact with it? → UI
• What is FlexMeasures?
  • What does it offer?
  • What problems solve?
• Which technologies does it use? Does it use Python?
• How can I customized/extend it?

From this exercise, I compiled a series of ideas for additions, modifications, and deletions of content in the different sections of our documentation.

Main Page

Link: https://flexmeasures.readthedocs.io/en/latest/index.html

Additions

1. Comment on the core technologies that we use: Python, PostgreSQL, Flask? These are some of the questions people will make first to consider FM a suitable solution. It's likely that they already know these technologies and can get along more easily.
2. Show an image of the UI of a schedule. This might replace or complement A quick glance at usage.
3. Explain the main technical features in bullet points as in PyPSA. We can borrow some text from this page.
4. I feel like we should outline the core features of FlexMeasures(Forecasting, Scheduling, Reporting) together with the three interface options (UI, CLI, API).

Modifications

1. Split Use cases into two sections: Use cases with links to details to V2G, buffer, etc and For Who.

2. Maybe it's too long. Move A possible road to start using FlexMeasures in your operation and Developer support to other sections/subsections.

3. Move the image Open Energy Flexibility Services more to the top with some modifications:

   • Show the Reporters, Schedulers and Forecasters + Interfaces (API, UI, CLI) + Plugins
   • We could use the diagram that @nicolas was working on recently.

4. Developer support section should be moved to its own page.

Deletions

• Table of contents at the end of the page. We already have this in the side menu.

---

Getting started

Link: https://flexmeasures.readthedocs.io/en/latest/getting-started.html

Inspired by PyPSA documentation, I think we should make Getting Started into a top-level section with the following subsections:

• Installation
• Quick Start
• Where to go next?

Additions

1. New subsection Installation: using the content of this page.
2. New subsection Quick start: merging the content of this and this pages.
3. New subsection Where to go next?: this should guide the users to choose the next page to visit, containing what the current Getting Started page has.

---

Concepts

Link

https://flexmeasures.readthedocs.io/en/latest/concepts/benefits.html

Additions

1. data model section, showing the diagram. The user needs to learn the language of FlexMeasures to be able to model Energy Optimization projects. We should give examples of the

Modifications

1. Move the Benefits page to the Main page, summarizing its content.
2. Rename Benefits from energy flexibility to something like Energy Flexibility because this section is explaining the benefits, but also the types.
3. Update Storage devices with the most recent ideas on scheduling, this section is mentioning "battery", "one-way_evse" and "two-way_evse" asset types.
   3.1. Keep future improvements (e.g page) in separate subsections to highlight what we have now. I feel like if you read the documentation lightly you might confuse between what we have now and what we are developing in the future.

Deletions

1. Remove section In-built smart functionality and create top-level sections for each of the features described: Scheduling, Reporting, Forecasting, (Monitoring?).

---

Tutorials

Additions

1. This section requires, probably, an introduction to outline the tutorials. Maybe this could go to the page Getting Started.

Modifications

1. Move Installation & First steps to a top level section Getting Started.
2. Rename Forecasting & scheduling to something like Compute Schedules & Forecasts.

Deletions

1. Remove subsection Install FlexMeasures and the database from Toy example: Scheduling a battery, from scratch. I would refer to Installaton & First steps in case someone lands in the tutorial without going through the installation first.

---

New Scheduling section

This new top-level section should describe the scheduling in great detail:

• StorageScheduler
  • Describing flex-model and flex-config, reusing what it's in the THE API/Notation section.
  • Explain the fallback mechanisms using the Asset or Sensor attributes to complete the flex-model.
  • Uses cases
    • How to model different energy scenarios? Static Batteries, EV, Heat
      Storage, curtailment.
• Describe the the model in linear_optimization scheduling function with LaTex.
• ShiftableLoadScheduler (in the future)
• Guide to creating your schedulers.

---

New Reporting section

This new top-level section should describe the reporting in great detail:

• Reporter as a subclass of DataGenerator.
  • Difference between (TBD) config (static attributes) and (TBD) input (dynamic attributes).ç
  • How to create your reporters in plugins?
• PandasReporter with some example reporters
• Page of reporters
  • AggregatorReporter
  • EnergyCostReporter

---

Feel free to add your own ideas and support the ideas that you find interesting.

[nhoening]

I agree with most of these proposals!
Some comments:

Main page

• Core technologies: We can mention them, but keep it short.
• Showing the UI of a schedule is a great idea. How about using tabs, like in the toy tutorial, and one first sees a schedule (e.g. Victor's latest image with a battery headroom, or simply a toy tutorial schedule), and the other tab shows the rough overview of commands and is titled "How it's done"?

Getting started

• I still believe that here we should not only address developers who want to install FlexMeasures. We give four groups their own attention here (users, hosters, plugin-devs, core-devs). However, in essence, the latter three need to install in some way, so I would say first address users, then highlight the new top-level Installaton & First steps section, and give the rest of the groups their own distinct pointers afterwards.
• Addendum: I also feel that all three groups should try the toy tutorial, not just hosters. Should also be a link next to installation.

Concepts

• Did you mean by "top-level" that these pages (Scheduling, Reporting, Forecasting) would live on the first level or under "Concepts"? I prefer the latter.
• Schedules: flex-model and flex-context should be explained above all other schedulers as they are intended to be used by all schedulers, and also greatly help with developing and using custom schedulers, I believe. I also want to talk about how you can tell FM about them. I want to store them on assets (as attributes), so they don't always have to be sent in with every request.
• About computations, we should in general speak about jobs, and how to trigger and retrieve them. The plans in Scheduling: which algorithms are planned & next iteration for a more REST-like API #598 (about exposing jobs in a REST-like fashion) would then have a great home. Maybe a concept page could be "How to tell FlexMeasures what to do", which is a lead-in for scheduling, forecasting, reporting etc
• Monitoring: I guess that could be a page. We made a start and we can point to plans. In the end, three of the four sections (besides scheduling) will look a bit empty. But I'm looking forward to a good representation what we have and what is planned.

Data model

• You did not finish your thoughts about examples there :)
• Each concept should get a small description - one sentence.
• I found that there are some attributes which matter, but are not explained enough (capacity_in_mw, sensors_to_show). Supported attributes need a home, and this page could be it. Later, the flex model and flex context will also be mentioned here. See Add capacity_in_mw to flex model for scheduling #335.

[Flix6x]

Can you leave a note in that docs discussion for me to maybe pick this up as well?

Originally posted by @nhoening in #885 (comment)

This is about giving the V2G flex model example a new place under tutorials.

[nhoening]

Work has started in #953