Documenting multi-repository software ecosystems

The preCICE case

Abstract

Documentation of software ecosystems is often scattered, and thus difficult to navigate and update. Moreover, separating the user documentation from the code repository often hides away the contribution and does not give appropriate credit in repository metrics. While documentation generation frameworks unify documentation and code, they pose certain limitations and primarily address a single repository. The preCICE coupling ecosystem includes components from multiple repositories with different technology stacks. This paper introduces the multi-repository solution implemented for the preCICE documentation, based on Git modules and a static site generator. This approach allows the documentation to be updated and reviewed together with the respective code contribution, ensuring up-to-date content and visibility of documentation contributions. This design also enables us to source content from third-party repositories or even the user forum, providing a comprehensive experience to the user. The website integrates with a search engine, provides analytics, and can be exported to a PDF file for archiving.