Quality aspects: Documentation
Importance of quality aspects
Implementation of quality aspects
| |
Which specific guidelines or tools are you aware of that help to enable the quality aspects? Provide short descriptions and/or URLs if possible, leave empty if there are no specific guidelines or tools. Provide general documentation :Guidelines |
Which specific guidelines or tools are you aware of that help to enable the quality aspects? Provide short descriptions and/or URLs if possible, leave empty if there are no specific guidelines or tools. Provide general documentation :Tools |
| 6 |
Many different tools / systems available, individual pages, readthedocs, … |
|
| 10 |
Documentation is typically in any guide, either in form of read-the-docs or gitlab pages or similar. |
|
| 12 |
provide a description of the sections that a readme should have |
Guidelines like https://www.freecodecamp.org/news/how-to-write-a-good-readme-file/ (no tool) |
| 18 |
|
Sphinx |
| 21 |
Read The Docs & Sphinx |
|
| |
Which specific guidelines or tools are you aware of that help to enable the quality aspects? Provide short descriptions and/or URLs if possible, leave empty if there are no specific guidelines or tools. Issue a scientific publication :Guidelines |
| 6 |
many relevant papers published in peer reviewed journals (Springer CSBS, JHEP or preprint servers such as arxiv.org or document servers e.g. zenodo |
| 10 |
The prompt dissemination of scientific results - including software - is in the best interest of the developers and typically a strategical goal of the research infrastructures. |
| 21 |
Journal of Open Source Software |
| |
Which specific guidelines or tools are you aware of that help to enable the quality aspects? Provide short descriptions and/or URLs if possible, leave empty if there are no specific guidelines or tools. Provide user examples :Guidelines |
Which specific guidelines or tools are you aware of that help to enable the quality aspects? Provide short descriptions and/or URLs if possible, leave empty if there are no specific guidelines or tools. Provide user examples :Tools |
| 6 |
Trainings and t |
|
| 10 |
As research software is typically complex, this is an essential |
|
| 18 |
|
Jupyter notebooks |
Level of confidence for answers in this section
| |
Are there any aspects and comments on software quality that you want to share? |
| 0 |
I’m interested in software discovery and once held a presentation about software quality indicators visible on discovery platforms. |
| 10 |
The habits of software development, maintenance and usage in the astro-particle community is diverse. This is - in parts - driven by the large experiments and research infrastructures involved that provide their own guidelines and practices. |
Auto-created summary
Summary of Mentioned Practices
- Read the Docs & Sphinx
- Used for providing general documentation, these tools are widely recognized for their effectiveness in creating and hosting technical documentation.
- Documentation Guidelines
- Publication Practices
- Publishing in peer-reviewed journals (e.g., Springer CSBS, JHEP) and open-access platforms (e.g., arXiv.org, Zenodo) for scientific publications is emphasized.
- Jupyter Notebooks
- Recommended for providing user examples, especially in research software due to their interactivity and comprehensiveness.
- CodeMeta and CFF Files
- Tools like CodeMeta and CFF (Citation File Format) are used for comprehensive metadata description, with generators and initializers available for ease of creation.
- Peer-Reviewed Journals & Open-Access Platforms
- The Journal of Open Source Software is mentioned as a publication venue, reinforcing the importance of disseminating research software results.
Linked URLs and Descriptions