User documentation and training at Belle II

TL;DR

This paper describes the comprehensive approach Belle II uses for user documentation, training, and support, including in-code documentation, testing, Q&A platforms, and workshops, to manage a decentralized collaboration effectively.

Contribution

It introduces integrated documentation, testing, and training strategies tailored for a large, decentralized scientific collaboration to improve user support and software adoption.

Findings

Documentation tied to software releases improves relevance.

Unit-tested tutorials prevent outdated content.

Q&A platform fosters expert discussions.

Abstract

Belle II is a rapidly growing collaboration with members from one hundred and nineteen institutes spread around the globe. The software development team of the experiment, as well as the software users, are very much decentralised. Together with the active development of the software, such decentralisation makes the adoption of the latest software releases by users an essential, but quite challenging task. To ensure the relevance of the documentation, we adopted the policy of in-code documentation and configured a website that allows us to tie the documentation to given releases. To prevent tutorials from becoming outdated, we covered them by unit-tests. For the user support, we use a question and answer service that not only reduces repetition of the same questions but also turned out to be a place for discussions among the experts. A prototype of a metasearch engine for the different sources of documentation has been developed. For training of the new users, we organise centralised StarterKit workshops attached to the collaboration meetings. The materials of the workshops are later used for self-education and organisation of local training sessions.