openjournals
Updating example paper
This pull request adds two new sections to the docs/example_paper.md documentation, providing important context about the Gala package's software design and research impact, as well as an AI usage disclosure statement. These additions improve transparency and clarify the architectural choices and community relevance of the package.
Documentation enhancements:
- Added a "Software Design" section detailing
Gala's hybrid Python/C architecture, rationale for building a new package instead of extending existing ones, and design philosophy prioritizing Astropy integration, composable potentials, and a flexible API. - Added a "Research Impact Statement" section summarizing
Gala's adoption in peer-reviewed research, integration into the Astropy ecosystem, use in academic curricula, and metrics on community uptake and contributions.
Transparency and compliance:
- Added an "AI usage disclosure" section stating that no generative AI tools were used in the development of the software, manuscript, or supporting materials.
:wave: @adrn - not sure if you knew this but we use your Gala JOSS paper as an example in our docs (although without your ORCiD these days 😬). Would you mind checking the changes in this PR to see if they look reasonable/logical? We're updating our paper format requirements and as such, I want to extend the example paper to include the new required sections.
(Side note, I used Claude to write these updates, but I'm looking for a :+1: that they describe Gala in a reasonable fashion).
Also, if you'd rather we found a different paper as an example, please just let us know.
I feel like some of the Software Design section is more Motivation (and might fit or overlap with the Statement of Need) more than being Software Design. I think it's important to get this right as an example, since it's probably what people will use as a model of this in their own papers, and I don't think this is yet right. Is this the level of detail we want? Is it the content we want?
Should the Research Impact section be slightly broader? I would also like to capture how contributors have added to the code over time, outside of the original team (or perhaps the authors of the paper), or at least to get some sense of the developer and user communities beyond examples of use / citations.
@arfon 👋 Sounds good!
RE: the text itself. Yea, the text isn't wrong, but (1) it definitely feels like it was written by Claude, and (2) I agree with @danielskatz that the comparisons to Galpy/scipy make it sound more like a statement of need. I'll draft a shorter "software design" section and post it here shortly!
BTW: since I have you all here ;) -- since I wrote the first JOSS paper (which is single authored), several other people have contributed significantly to the package, and there are some cool new features. Do you have a recommendation for what to do in situations like this? Should I submit a new Gala paper with the co-authors and a description of the new stuff? Happy to move this discussion to a different / more appropriate place, but this thread just reminded me I've been meaning to ask...
RE: the text itself. Yea, the text isn't wrong, but (1) it definitely feels like it was written by Claude, and (2) I agree with @danielskatz that the comparisons to Galpy/scipy make it sound more like a statement of need. I'll draft a shorter "software design" section and post it here shortly!
:zap: thank you!
BTW: since I have you all here ;) -- since I wrote the first JOSS paper (which is single authored), several other people have contributed significantly to the package, and there are some cool new features. Do you have a recommendation for what to do in situations like this? Should I submit a new Gala paper with the co-authors and a description of the new stuff? Happy to move this discussion to a different / more appropriate place, but this thread just reminded me I've been meaning to ask...
Typically we ask that the 'delta' between the original a follow up paper/submission represents a substantial scholarly contribution in and of itself. Perhaps we can chat about it when we have our call? It's definitely possible (and has happened before) but can be a little nuanced.