Documenting complex research software ecosystems

Talk at the 6th Conference for Research Software Engineering in Germany (deRSE26).

Abstract:

While a valid and important contribution, documentation is often scattered, limiting its findability, accessibility, and searchability. Moreover, separating the user documentation from the code repository often hides away the contribution and does not give appropriate credit in repository metrics. While solutions such as Read the Docs or Doxygen help render documentation integrated in code, they typically address a single repository and pose certain limitations in programming languages and rendering. The preCICE coupling ecosystem includes components from multiple repositories, written in different programming languages, and developed by multiple authors. The documentation is sourced from these different repositories and rendered on a central website (making it findable, accessible, cross-linked, searchable, and easily archivable). This allows the documentation to be updated in the same workflow as the respective code contribution, ensuring up-to-date content and recognition of documentation contributions. The documentation is also easily editable by the community, as an "Edit me" button points to the respective files on GitHub. This design also enables us to source documentation from external repositories or even the user forum, providing a comprehensive experience to the user. The website also integrates with a search engine (Algolia), a cookie-free analytics solution (Plausible), and a PDF exporter (Prince). The content is the result of user observation, answering questions with updates in documentation. Over five years, the documentation of preCICE has matured, it has received encouraging feedback by the community, and it has influenced third-party projects. This talk will give an overview of common approaches and issues in documenting research software, it will describe the architecture of the preCICE documentation, and provide lessons learned that might be useful to the wider RSE community.