Documentation discrepancies between repo and website.

[AlexPatrie]

Abstract

I have been using biosimulators.org as the perspective for our “landing page” as it is our own unique little section of the internet. I am also inspired by other major Python packages whose primary source of documentation is their own website (sometimes directly on the home page!).

Evidence

Given this viewpoint, it is clear that the presentation of entrypoints on our website needs some help. To support my assertion, I will reference the following examples:

1. For example, if you were to click on “Tutorial” under “Contents” on the
   “BioSimulators-COPASI documentation” page
   

...only the cli and Docker entrypoints are referenced. To me, this is
confusing for a ‘Tutorials’ or ‘Getting Started’ page as only some of
the entrypoints from the “Overview” section are referenced. As a programmer it can be difficult to navigate the documentation, let alone someone with no coding experience.

2. Furthermore, when you click on "Tutorial" here: ...
   

   ...you are taken to a binder tutorial which ITSELF is a demonstration of the programmatic capabilities of the Python api.

3. Finally, there are several references to this page which is on the (for all intents and purposes) very different Biosimulations website.

I can understand why these methods are highlighted as they are the methods that require the least amount of setup. Of course, there may exist the philosophical "best practice" of interacting with this repo, but I fear that there is an overall lack of consistency in regard to the scope of a user's ability to interact with this fantastic tool.

Proposal

• Create a landing page which references each application entrypoint in an explicit manner
• Remove or change the reference to the runBiosimulations getting started guide to be a Biosimulators specific reference
• Create a visualization of the relationship between Biosimulators, Biosimulations, and runBiosimulations. Let this visualization also describe their individual purpose/role in the framework.
• Create a smart tool for model inference. Leverage the current abilities to identify simulation objects to provide the "best model for the job".
• Leverage the biosimulators-tutorials repo and add a pre-configured, shareable, editable Google Colab "sandbox" notebook to the repo (see this pull request)

[eagmon]

This issue seems very much inline with our current effort on simplifying and streamlining the biosimulators/biosimulations paradigm, and the web front end. It is great you are gathering these resources @AlexPatrie, we should make use of your recent experiences to improve how we present our paradigm. And it seems like some of that effort should focus on consolidating resources and improving how they are presented and accessed.

I agree about making more explicit references to application entry points. These should be under each tool's page on biosimulators.org. I also think we should put more resources in each tool's GitHub Biosimulator_toolname repository, rather than in a shared online space for all the tools. Notebooks and tutorials are appropriate here, showing how to use the particular tool. We can maybe make a GitHub pages that can access each of these tutorials and puts them on a website, kind of like how I have done with this tutorial for bigraph-viz: https://vivarium-collective.github.io/bigraph-viz/notebooks/basics.html