Restructuring and unifying the documentation

No, this time this is not an April’s fools joke. As discussed last week in our first Community Hour, we are starting a large re-writing of our website,, which currently looks like this:

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:

As a new user, one would probably follow this path currently:

  1. Discover preCICE on via a search engine or linked page :smiley:
  2. Start looking around, as there is no “Start here” or “Download” button (preCICE is not a click-and-play, self-contained software package anyway) :confused:
  3. Find the “Resources” page and then jump to GitHub for the latest release and (hopefully) install the latest binary package :partying_face:
  4. 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). :cold_sweat:
  5. Follow (sometimes outdated) links in the tutorial to install at least two (third-party) solvers :dizzy_face:
  6. Follow links in the tutorials to the adapters’ wiki pages or Readme files :confounded:
  7. Often encounter problems and (hopefully) contact us here or on Gitter :triumph:

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, 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. :star_struck:

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?

There was already some comment in this post: Meet preCICE: 1st community hour (videoconference): April 15, 2020

The proposed changes sound good to me.

Does this mean you will separate the homepage (information for users) stronger from GitHub (information for developers) and close the GitHub Wiki?

Yes: We will remove the content for the wiki and keep (at least for a while) some empty pages as placeholders to redirect to the new places.

The “information for developers” is currently little in the wiki, and quite some on README files and Doxygen. We will now:

  • Move everything that could be useful to a user (e.g. API documentation, Config visualizer & other tools) to the homepage.
  • Create a new “portal” for contributors in the homepage (general information for anyone interested to contribute)
  • Keep the repository-specific contribution guides, issue templates etc on the natural places on GitHub

It is a bit unclear what will become of Doxygen. We will probably keep it in a “ghost” mode, with the bare minimum functionality, moving all the additional content to either the homepage or the special GitHub pages for the precice/precice repository.