Cheatsheets for the most common methods

[MakisH]

An old idea / request is to provide cheatsheets for the preCICE API. We could even make one that includes all bindings. We should then add this on the website (and find a way to remember to update it), from which we could also automatically generate a PDF file.

@fsimonis raised this again in the context of the preCICE course, but I think it would be best to implement this in the open.

[uekerman]

How would the cheat sheet be different from our current API reference + the step-by-step guide?
I am a bit afraid that we duplicate information and then forget to update. Users also get confused if information is duplicated in my opinion.
Maybe we need to improve what we already have?
For the Python bindings, what we could do is to render the API reference and include it in the website? This would be no additional material, only a different presentation.

[fsimonis]

How would the cheat sheet be different from our current API reference + the step-by-step guide?

I imagine the cheat sheet to be a short overview of the most important functions of the (python) API in a printable A4 format. This could be printed and help users to find the function they are looking for and how the parameters are supposed to look.

Good would be to automatically generate this from the python bindings / doxygen.

[MakisH]

I understand and agree with the duplication argument and we need to find a solution for that, if we decide to implement something.

Issues at the moment:

• API reference: only for C++, but also everything of the C++ API (easy to get lost there)
• Ste-by-step guide: multiple pages (not searchable)

I also imagine that the cheatsheet to be a very short overview of the most basic commands, in one (A4 when printable) page, but also for other languages. We once even though of putting that on a tea cup.

Regarding the target audience:

• A beginner may not really be able to follow that
• An experienced user knows where to look for specific commands
• ... which leaves us with the intermediate level user that mainly needs this often. Not sure this is a real use case, then.

Does even a printable cheatsheet make sense in our case? Would any user need to look at the same command for more than a couple of times?

[uekerman]

Mmh. I think what we are really missing is an online reference of the Python API integrated into the website. Maybe let's do this first before we conclude on whether we need anything more?

[uekerman]

Currently, the Python API is also not searchable on the website, e.g. is_ongoing yields no results. This is really unfortunate.

[MakisH]

Currently, the Python API is also not searchable on the website, e.g. is_ongoing yields no results. This is really unfortunate.

The "expected" solution for that would be to add a readthedocs rendering of the Python API, but this would probably overshadow the website and confuse users.

One alternative would be that we generate markdown from Sphinx documentation and render it on our website.

Other than that, such a cheatsheet for all bindings (I include Fortran, Matlab, Julia here) would be an easy workaround, which would also allow us to keep track of what is inconsistent across bindings.

[uekerman]

Btw, also the C++ API documentation is not findable through the search 🙈

[fsimonis]

We could integrate precice/doxygen into the website.
Then the Angolia indexer should pick up the entire C++ documentation.
We could then do the same for the python documentation.

@chlorenz Is is possible to filter this agolia index somehow? The Gem doesn't seem to provide this functionality.

[MakisH]

Regarding cheatsheets, we could also offload that to the community. This platform seems to have quite some nice cheatsheets, which are indexed by DuckDuckGo: https://cheatography.com/

[uekerman]

#211 is also a partial solution

[MakisH]

Discussion:

• The API today is much shorter and clearer, so that you nowadays easily look at the full thing as a newbie.
• We still have ways to see the full API in the native system of each language.
• We want to avoid duplication as much as possible.

I also believe that #211 is the proper solution, and we can close this issue.