-
Notifications
You must be signed in to change notification settings - Fork 3
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Documentation discrepancies between repo and website. #61
Comments
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 |
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:
“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.
Furthermore, when you click on "Tutorial" here: ...
![tutorial](https://user-images.githubusercontent.com/105522603/234301420-9ce6095c-1d2b-4a35-91aa-7bc4212b165f.png)
...you are taken to a binder tutorial which ITSELF is a demonstration of the programmatic capabilities of the Python api.
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
The text was updated successfully, but these errors were encountered: