This is already a largely improved version from the previous state. However, the structure remains more-or-less the same and it mainly serves as a portal to the rest of the available resources. As such, we often forget updating it and is sometimes a bit confusing, especially for new users.
Furthermore, our documentation is currently split over the following places:
- The preCICE Wiki
- The adapters’ and other tools’ Wiki and Readme files (e.g. OpenFOAM adapter wiki)
- The Doxygen code documentation
- The main website, regarding features and available resources
As a new user, one would probably follow this path currently:
- Discover preCICE on precice.org via a search engine or linked page
- Start looking around, as there is no “Start here” or “Download” button (preCICE is not a click-and-play, self-contained software package anyway)
- Find the “Resources” page and then jump to GitHub for the latest release and (hopefully) install the latest binary package
- Go back to “Resources” and then find the preCICE Wiki homepage, or choose one of the tutorials listed (probably the one closer to the intended application, which may not be the easiest/most clearly described tutorial).
- Follow (sometimes outdated) links in the tutorial to install at least two (third-party) solvers
- Follow links in the tutorials to the adapters’ wiki pages or Readme files
- Often encounter problems and (hopefully) contact us here or on Gitter
The reasons for this spaghetti experience are, as expected, historical, as well as a lack of resources and preCICE being primarily driven by academic/research goals. However, having grown a considerably large community and ecosystem, it is the right time to “clean up” a little bit, also based on the feedback we received during our 1st preCICE workshop.
After a short brainstorming, we decided to start from scratch and unify the documentation, moving (almost) everything to precice.org, keeping some developer-specific information on GitHub, and adding more information about our community (statistics, publications using preCICE, contribution guides, etc).
Here is a mindmap of the structure we converged to (created with markmap):
- The main page (“preCICE”) will be one long page with the basic information everybody needs to have before doing anything else. Each “section” should more-or-less fit in the screen and should give clear next steps, if applicable. We could even show a simple “terminal view” (e.g. similar to the Vagrant homepage) or an animation (e.g. with asciinema), demonstrating the basic concept alredy in the first page.
- In the “Quickstart” page, we will describe the simplest, most common way to get preCICE, and the simplest tutorial one could try and would still be a complete simulation with established solvers.
- The “Docs” page would have all the information we currently have in wikis, with more information on using the API of preCICE. Similar for the “Tutorials”.
- The “Community” page would be partially new, listing major contributors, describing how to become a contributor and where we need help (pointing to GitHub contribution guides for details on each repository), and showcasing testimonials and publications, as now. We could also integrate users’ publications here. The preCICE Workshop would have a permanent place here, alongside future events.
- A “Blog” section is something we wanted since longer, to incorporate posts like this one. We could even integrate Discourse (from now on “preCICE Forum”) as a blogging platform.
Particularly regarding the section “installing preCICE”, the user should first select the target system (i.e. laptop/Ubuntu/20.04) and then get the exact instructions to get preCICE, in a way that should always work.
The complete website should be searchable from the same place.
Finally, a reason we insisted on using the GitHub Wiki for a while was the possibility to easily edit it. We can still keep this functionality (and even extend it), following a pattern similar to the GitLab, Docker, and SU2 documentation:
Your comments are very welcome! What would be the most important feature of the new website for you? What information was currently the most difficult for you to find? Any ideas/suggestions about the implementation?