mirror of
https://scm.cms.hu-berlin.de/methodenlabor/doc_documentation.git
synced 2025-06-08 01:49:07 +00:00
updated literature based on our shared Zotero library. Note that some of the original references seemingly were generated by LLMs and at least partially fictitious
This commit is contained in:
Till Grallert
parent
f54c779f9f
commit
e41d3c4c3e
@ -71,15 +71,15 @@ gute Dokumentation als zentrale Voraussetzung, um Forschungssoftware
|
||||
**auffindbar, nachvollziehbar und wiederverwendbar** zu machen.
|
||||
|
||||
[Alle Empfehlungen stützen sich auf Literatur und etablierte Richtlinien
|
||||
[@prlic2012ten; @wilson2017good; @katz2021open;
|
||||
@endings2020principles].]{.aside}
|
||||
[@PrlicProcter2012TenSimpleRules; @WilsonEtAl2017Goodenoughpractices; @BarkerEtAl2022IntroducingFAIR;
|
||||
@EndingsPrinciples221].]{.aside}
|
||||
|
||||
Dieser Anforderungskatalog richtet sich an Forschende, die keine
|
||||
Vollzeit-Programmierer sind, und soll **wissenschaftlich fundierte Richtlinien**
|
||||
für die Dokumentation von Forschungssoftware liefern. Die Empfehlungen
|
||||
berücksichtigen Best Practices des Research Software Engineering (RSE) und
|
||||
insbesondere die Prinzipien des _Endings-Projekts_ für digitale Langlebigkeit
|
||||
[@endings2020principles]. Ziel ist es, ein praxistaugliches Gerüst
|
||||
[@EndingsPrinciples221]. Ziel ist es, ein praxistaugliches Gerüst
|
||||
bereitzustellen, das – trotz Zeitknappheit – die wesentlichen
|
||||
Dokumentationsaspekte abdeckt, um sowohl die **Nachvollziehbarkeit** der
|
||||
Ergebnisse als auch eine **Weiterverwendung** der Software zu ermöglichen. Im
|
||||
@ -221,7 +221,7 @@ Nachnutzung nicht zu behindern. Zudem sollte angegeben werden, wie die Software
|
||||
_“Zitation”_ oder eine CITATION-Datei beschreibt, welche Publikation oder
|
||||
welcher DOI bei Verwendung der Software in wissenschaftlichen Arbeiten anzugeben
|
||||
ist. Dies erhöht die akademische Sichtbarkeit und stellt sicher, dass
|
||||
Autor\*innen Credits für ihre Software bekommen[@smith2016software]. Schließlich
|
||||
Autor\*innen Credits für ihre Software bekommen [@SmithEtAl2016Softwarecitation]. Schließlich
|
||||
ist es sinnvoll, eine **Versionsnummer** der Software zu nennen (idealerweise in
|
||||
README und im Tool selbst), damit Nutzer wissen, auf welche Ausgabe sich die
|
||||
Dokumentation bezieht – insbesondere, wenn es im Laufe der Zeit Aktualisierungen
|
||||
|
||||
@ -1,69 +1,173 @@
|
||||
@article{wilson2017good,
|
||||
title={Good enough practices in scientific computing},
|
||||
author={Wilson, Greg and Bryan, Jennifer and Cranston, Karen and Kitzes, Justin and Nederbragt, Lex and Teal, Tracy K},
|
||||
journal={PLoS computational biology},
|
||||
volume={13},
|
||||
number={6},
|
||||
pages={e1005510},
|
||||
year={2017},
|
||||
publisher={Public Library of Science}
|
||||
% this bibliography is maintained in Zotero with the tag 'project: documentation'
|
||||
% prefered format is BibLaTeX
|
||||
|
||||
@article{BarkerEtAl2022IntroducingFAIR,
|
||||
title = {Introducing the {{FAIR Principles}} for Research Software},
|
||||
author = {Barker, Michelle and Chue Hong, Neil P. and Katz, Daniel S. and Lamprecht, Anna-Lena and Martinez-Ortiz, Carlos and Psomopoulos, Fotis and Harrow, Jennifer and Castro, Leyla Jael and Gruenpeter, Morane and Martinez, Paula Andrea and Honeyman, Tom},
|
||||
date = {2022-10-14},
|
||||
journaltitle = {Scientific Data},
|
||||
shortjournal = {Sci Data},
|
||||
volume = {9},
|
||||
number = {1},
|
||||
pages = {622},
|
||||
publisher = {Nature Publishing Group},
|
||||
issn = {2052-4463},
|
||||
doi = {10.1038/s41597-022-01710-x},
|
||||
url = {https://www.nature.com/articles/s41597-022-01710-x},
|
||||
urldate = {2024-09-10},
|
||||
abstract = {Research software is a fundamental and vital part of research, yet significant challenges to discoverability, productivity, quality, reproducibility, and sustainability exist. Improving the practice of scholarship is a common goal of the open science, open source, and FAIR (Findable, Accessible, Interoperable and Reusable) communities and research software is now being understood as a type of digital object to which FAIR should be applied. This emergence reflects a maturation of the research community to better understand the crucial role of FAIR research software in maximising research value. The FAIR for Research Software (FAIR4RS) Working Group has adapted the FAIR Guiding Principles to create the FAIR Principles for Research Software (FAIR4RS Principles). The contents and context of the FAIR4RS Principles are summarised here to provide the basis for discussion of their adoption. Examples of implementation by organisations are provided to share information on how to maximise the value of research outputs, and to encourage others to amplify the importance and impact of this work.},
|
||||
langid = {english},
|
||||
keywords = {project: documentation,Project: Methods Lab 🥼,RSE: Research Software Engineering}
|
||||
}
|
||||
|
||||
@article{prlic2012ten,
|
||||
title={Ten simple rules for documenting scientific software},
|
||||
author={Prli{\'c}, Andreas and Procter, James B},
|
||||
journal={PLoS Computational Biology},
|
||||
volume={8},
|
||||
number={12},
|
||||
pages={e1002802},
|
||||
year={2012},
|
||||
publisher={Public Library of Science}
|
||||
@book{CremerEtAl2024Projektmanagement,
|
||||
title = {Projektmanagement und Digital Humanities: Zur klugen Gestaltung der Zusammenarbeit},
|
||||
editor = {Cremer, Fabian and Dogunke, Swantje and Neubert, Anna Maria and Wübbena, Thorsten},
|
||||
date = {2024-04},
|
||||
publisher = {Bielefeld University Press},
|
||||
location = {Bielefeld},
|
||||
doi = {10.14361/9783839469675},
|
||||
abstract = {Die Professionalisierung des Projektmanagements in den Digital Humanities: Theorie und Praxis zum Weiterdenken.},
|
||||
langid = {ngerman},
|
||||
keywords = {field: Digital Humanities (DH),Project management,project: documentation,Project: Methods Lab 🥼,status: currently reading}
|
||||
}
|
||||
|
||||
@article{smith2016software,
|
||||
title={Software citation principles},
|
||||
author={Smith, Arfon M and Katz, Daniel S and Niemeyer, Kyle E and FORCE11 Software Citation Working Group and others},
|
||||
journal={PeerJ Computer Science},
|
||||
volume={2},
|
||||
pages={e86},
|
||||
year={2016},
|
||||
publisher={PeerJ Inc.}
|
||||
@article{DiehlEtAl2025JournalOpenSource,
|
||||
title = {The {{Journal}} of {{Open Source Software}} ({{JOSS}}): {{Bringing Open-Source Software Practices}} to the {{Scholarly Publishing Community}} for {{Authors}}, {{Reviewers}}, {{Editors}}, and {{Publishers}}},
|
||||
shorttitle = {The {{Journal}} of {{Open Source Software}} ({{JOSS}})},
|
||||
author = {Diehl, Patrick and Soneson, Charlotte and Kurchin, Rachel C. and Mounce, Ross and Katz, Daniel S.},
|
||||
date = {2025-02-04},
|
||||
journaltitle = {Journal of Librarianship and Scholarly Communication},
|
||||
volume = {12},
|
||||
number = {2},
|
||||
publisher = {Iowa State University Digital Press},
|
||||
issn = {2162-3309},
|
||||
doi = {10.31274/jlsc.18285},
|
||||
url = {https://www.iastatedigitalpress.com/jlsc/article/id/18285/},
|
||||
urldate = {2025-05-15},
|
||||
abstract = {Introduction: Open-source software (OSS) is a critical component of open science, but contributions to the OSS ecosystem are systematically undervalued in the current academic system. The Journal of Open Source Software (JOSS) contributes to addressing this by providing a venue (that is itself free, diamond open access, and all open-source, built in a layered structure using widely available elements/services of the scholarly publishing ecosystem) for publishing OSS, run in the style of OSS itself. A particularly distinctive element of JOSS is that it uses open peer review in a collaborative, iterative format, unlike most publishers. Additionally, all the components of the process—from the reviews to the papers to the software that is the subject of the papers to the software that the journal runs—are open. Background: We describe JOSS’s history and its peer review process using an editorial bot, and we present statistics gathered from JOSS’s public review history on GitHub showing an increasing number of peer reviewed papers each year. We discuss the new JOSSCast and use it as a data source to understand reasons why interviewed authors decided to publish in JOSS. Discussion and Outlook: JOSS’s process differs significantly from traditional journals, which has impeded JOSS’s inclusion in indexing services such as Web of Science. In turn, this discourages researchers within certain academic systems, such as Italy’s, which emphasize the importance of Web of Science and/or Scopus indexing for grant applications and promotions. JOSS is a fully diamond open-access journal with a cost of around US\$5 per paper for the 401 papers published in 2023. The scalability of running JOSS with volunteers and financing JOSS with grants and donations is discussed.},
|
||||
issue = {2},
|
||||
langid = {english},
|
||||
keywords = {project: documentation,Project: Methods Lab 🥼}
|
||||
}
|
||||
|
||||
@article{maria2019jupyter,
|
||||
title={Jupyter notebooks—a publishing format for reproducible computational workflows},
|
||||
author={Kluyver, Thomas and Ragan-Kelley, Benjamin and P{\'e}rez, Fernando and Granger, Brian and Bussonnier, Matthias and Frederic, Jonathan and Kelley, Kyle and Hamrick, Jessica B and Grout, Jason and Corlay, Sylvain and others},
|
||||
journal={Positioning and Power in Academic Publishing: Players, Agents and Agendas},
|
||||
volume={20},
|
||||
@misc{EndingsPrinciples221,
|
||||
title = {Endings {{Principles}} for {{Digital Longevity}}},
|
||||
shorttitle = {Endings {{Principles}}},
|
||||
author = {{Endings Project Team}},
|
||||
date = {2023-03-03},
|
||||
url = {https://endings.uvic.ca/principles.html},
|
||||
urldate = {2024-05-14},
|
||||
abstract = {Enabling Sustainable Digital Humanities Projects},
|
||||
langid = {english},
|
||||
version = {2.2.1},
|
||||
keywords = {project: documentation,Project: Methods Lab 🥼,Project: Tool Registry 🧰,talk: 2024 Bochum,writing: 2024 Tool Registry}
|
||||
}
|
||||
|
||||
@inproceedings{KluyverEtAl2016JupyterNotebookspublishing,
|
||||
title = {Jupyter {{Notebooks}} – a Publishing Format for Reproducible Computational Workflows},
|
||||
author = {Kluyver, Thomas and Ragan-Kelley, Benjamin and Pérez, Fernando and Granger, Brian and Bussonnier, Matthias and Frederic, Jonathan and Kelley, Kyle and Hamrick, Jessica and Grout, Jason and Corlay, Sylvain and Ivanov, Paul and Avila, Damián and Abdalla, Safia and Willing, Carol and Jupyter development team},
|
||||
editor = {Loizides, Fernando and Scmidt, Birgit},
|
||||
namea = {Kluyver, Thomas and Ragan-Kelley, Benjamin and Pérez, Fernando and Granger, Brian and Bussonnier, Matthias and Frederic, Jonathan and Kelley, Kyle and Hamrick, Jessica and Grout, Jason and Corlay, Sylvain and Ivanov, Paul and Avila, Damián and Abdalla, Safia and Willing, Carol and Jupyter development team and Loizides, Fernando and Scmidt, Birgit},
|
||||
nameatype = {collaborator},
|
||||
date = {2016},
|
||||
pages = {87--90},
|
||||
year={2016},
|
||||
publisher={IOS Press}
|
||||
}
|
||||
|
||||
@misc{endings2020principles,
|
||||
title = {Endings Principles for Digital Longevity},
|
||||
author = {{Endings Project}},
|
||||
year = {2020},
|
||||
url = {https://endings.uvic.ca/principles.html}
|
||||
}
|
||||
|
||||
@article{katz2021open,
|
||||
title={The Journal of Open Source Software (JOSS)},
|
||||
author={Katz, Daniel S and Niemeyer, Kyle E and Smith, Arfon M},
|
||||
journal={PeerJ Computer Science},
|
||||
volume={7},
|
||||
pages={e432},
|
||||
year={2021},
|
||||
publisher={PeerJ Inc.}
|
||||
publisher = {IOS Press},
|
||||
doi = {10.3233/978-1-61499-649-1-87},
|
||||
url = {https://eprints.soton.ac.uk/403913/},
|
||||
urldate = {2025-05-15},
|
||||
abstract = {It is increasingly necessary for researchers in all fields to write computer code, and in order to reproduce research results, it is important that this code is published. We present Jupyter notebooks, a document format for publishing code, results and explanations in a form that is both readable and executable. We discuss various tools and use cases for notebook documents.},
|
||||
eventtitle = {20th {{International Conference}} on {{Electronic Publishing}} (01/01/16)},
|
||||
langid = {english},
|
||||
keywords = {project: documentation,Project: Methods Lab 🥼}
|
||||
}
|
||||
|
||||
@article{lamprecht2020towards,
|
||||
title={Towards FAIR principles for research software},
|
||||
author={Lamprecht, Anna-Lena and Garcia, Leyla and Kuzak, Mateusz and Martinez, Carlos and Arcila, Ricardo and Martin Del Pico, Eva and others},
|
||||
journal={Data Science},
|
||||
title = {Towards {{FAIR}} Principles for~Research~Software},
|
||||
author = {Lamprecht, Anna-Lena and Garcia, Leyla and Kuzak, Mateusz and Martinez, Carlos and Arcila, Ricardo and Martin Del Pico, Eva and Dominguez Del Angel, Victoria and family=Sandt, given=Stephanie, prefix=van de, useprefix=true and Ison, Jon and Martinez, Paula Andrea and McQuilton, Peter and Valencia, Alfonso and Harrow, Jennifer and Psomopoulos, Fotis and Gelpi, Josep Ll. and Chue Hong, Neil and Goble, Carole and Capella-Gutierrez, Salvador},
|
||||
date = {2020-06-12},
|
||||
journaltitle = {Data Science},
|
||||
volume = {3},
|
||||
number = {1},
|
||||
pages = {37--59},
|
||||
year={2020},
|
||||
publisher={IOS Press}
|
||||
publisher = {SAGE Publications},
|
||||
issn = {2451-8484},
|
||||
doi = {10.3233/DS-190026},
|
||||
url = {https://doi.org/10.3233/DS-190026},
|
||||
urldate = {2025-05-15},
|
||||
abstract = {The FAIR Guiding Principles, published in 2016, aim to improve the findability, accessibility, interoperability and reusability of digital research objects for both humans and machines. Until now the FAIR principles have been mostly applied to research data. The ideas behind these principles are, however, also directly relevant to research software. Hence there is a distinct need to explore how the FAIR principles can be applied to software. In this work, we aim to summarize the current status of the debate around FAIR and software, as basis for the development of community-agreed principles for FAIR research software in the future. We discuss what makes software different from data with regard to the application of the FAIR principles, and which desired characteristics of research software go beyond FAIR. Then we present an analysis of where the existing principles can directly be applied to software, where they need to be adapted or reinterpreted, and where the definition of additional principles is required. Here interoperability has proven to be the most challenging principle, calling for particular attention in future discussions. Finally, we outline next steps on the way towards definite FAIR principles for research software.},
|
||||
langid = {english},
|
||||
keywords = {project: documentation,Project: Methods Lab 🥼}
|
||||
}
|
||||
|
||||
@article{Lee2018Tensimplerules,
|
||||
title = {Ten Simple Rules for Documenting Scientific Software},
|
||||
author = {Lee, Benjamin D.},
|
||||
date = {2018-12-20},
|
||||
journaltitle = {PLOS Computational Biology},
|
||||
shortjournal = {PLOS Computational Biology},
|
||||
volume = {14},
|
||||
number = {12},
|
||||
pages = {e1006561},
|
||||
publisher = {Public Library of Science},
|
||||
issn = {1553-7358},
|
||||
doi = {10.1371/journal.pcbi.1006561},
|
||||
url = {https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1006561},
|
||||
urldate = {2025-05-15},
|
||||
langid = {english},
|
||||
keywords = {project: documentation,Project: Methods Lab 🥼}
|
||||
}
|
||||
|
||||
@article{PrlicProcter2012TenSimpleRules,
|
||||
title = {Ten {{Simple Rules}} for the {{Open Development}} of {{Scientific Software}}},
|
||||
author = {Prlić, Andreas and Procter, James B.},
|
||||
date = {2012-12-06},
|
||||
journaltitle = {PLOS Computational Biology},
|
||||
shortjournal = {PLOS Computational Biology},
|
||||
volume = {8},
|
||||
number = {12},
|
||||
pages = {e1002802},
|
||||
publisher = {Public Library of Science},
|
||||
issn = {1553-7358},
|
||||
doi = {10.1371/journal.pcbi.1002802},
|
||||
url = {https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1002802},
|
||||
urldate = {2025-05-15},
|
||||
langid = {english},
|
||||
keywords = {project: documentation,Project: Methods Lab 🥼}
|
||||
}
|
||||
|
||||
@article{SmithEtAl2016Softwarecitation,
|
||||
title = {Software Citation Principles},
|
||||
author = {Smith, Arfon M. and Katz, Daniel S. and Niemeyer, Kyle E.},
|
||||
date = {2016},
|
||||
journaltitle = {PeerJ Computer Science},
|
||||
shortjournal = {PeerJ Comput. Sci.},
|
||||
volume = {2},
|
||||
publisher = {PeerJ Inc.},
|
||||
issn = {2376-5992},
|
||||
doi = {10.7717/peerj-cs.86},
|
||||
url = {https://peerj.com/articles/cs-86},
|
||||
urldate = {2020-09-11},
|
||||
abstract = {Software is a critical part of modern research and yet there is little support across the scholarly ecosystem for its acknowledgement and citation. Inspired by the activities of the FORCE11 working group focused on data citation, this document summarizes the recommendations of the FORCE11 Software Citation Working Group and its activities between June 2015 and April 2016. Based on a review of existing community practices, the goal of the working group was to produce a consolidated set of citation principles that may encourage broad adoption of a consistent policy for software citation across disciplines and venues. Our work is presented here as a set of software citation principles, a discussion of the motivations for developing the principles, reviews of existing community practice, and a discussion of the requirements these principles would place upon different stakeholders. Working examples and possible technical solutions for how these principles can be implemented will be discussed in a separate paper.},
|
||||
langid = {english},
|
||||
keywords = {Eintrag bereinigt,PDF (Dropbox),project: documentation,Project: Methods Lab 🥼,Research Software Engineering}
|
||||
}
|
||||
|
||||
@article{WilsonEtAl2017Goodenoughpractices,
|
||||
title = {Good Enough Practices in Scientific Computing},
|
||||
author = {Wilson, Greg and Bryan, Jennifer and Cranston, Karen and Kitzes, Justin and Nederbragt, Lex and Teal, Tracy K.},
|
||||
date = {2017-06-22},
|
||||
journaltitle = {PLOS Computational Biology},
|
||||
shortjournal = {PLOS Computational Biology},
|
||||
volume = {13},
|
||||
number = {6},
|
||||
pages = {e1005510},
|
||||
publisher = {Public Library of Science},
|
||||
issn = {1553-7358},
|
||||
doi = {10.1371/journal.pcbi.1005510},
|
||||
url = {https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1005510},
|
||||
urldate = {2025-05-15},
|
||||
abstract = {Author summary Computers are now essential in all branches of science, but most researchers are never taught the equivalent of basic lab skills for research computing. As a result, data can get lost, analyses can take much longer than necessary, and researchers are limited in how effectively they can work with software and data. Computing workflows need to follow the same practices as lab projects and notebooks, with organized data, documented steps, and the project structured for reproducibility, but researchers new to computing often don't know where to start. This paper presents a set of good computing practices that every researcher can adopt, regardless of their current level of computational skill. These practices, which encompass data management, programming, collaborating with colleagues, organizing projects, tracking work, and writing manuscripts, are drawn from a wide variety of published sources from our daily lives and from our work with volunteer organizations that have delivered workshops to over 11,000 people since 2010.},
|
||||
langid = {english},
|
||||
keywords = {project: documentation,Project: Methods Lab 🥼}
|
||||
}
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user