Joss: What should/shouldn't the paper include?

[kyleniemeyer]

Recording a comment from a conversation earlier today with @arfon and @danielskatz: should there be a way to allow discussion of implementation details or underlying theory (e.g., equations)? Or should that be mandated in the software documentation?

Some suggestions/options:

• Leave implementation/theory details in documentation.
• Keep "main" section of paper empty, but allow appendices.
• Allow "methodology" or "implementation details" (e.g.) section in paper

[Kevin-Mattheus-Moerman]

I like that the papers can be super short and high speed i.e. a short abstract style. However, I also see value in allowing longer, more detailed and traditional looking papers. Some authors may indeed wish to provide a more thorough discussion, include references, figures, equations etc.. They may feel the paper is the academic front page for presenting/citing the software and as such it could describe it more thoroughly than just and abstract.
So perhaps we could allow both types, either a short abstract style (where more detailed informations has be clear from the documentation), or a longer paper.

[danielskatz]

I think we should focus on where we can make a unique contribution, which is the short abstract style. There are already a number of journals like SoftwareX and JORS that are good for longer articles, and I would rather try to influence them towards a better practice than compete with them, but this is just a personal opinion - if you think we have something valuable enough to offer people who want to write longer articles, we can certainly do both.

[arfon]

I think I agree with Dan here. To me, the core value-add here for authors is that they _don't_ need to write a full paper.

I would suggest we launch as-is and if we get lots of people asking to submit longer-form pieces then perhaps we could revisit?

[Kevin-Mattheus-Moerman]

Okay that sounds good.

[daattali]

Just came here to say that to me it seemed very odd to submit such a short paper.

Most of my scientific packages do include longer vignettes with details on the theory and usage, and my instinct was to just use my vignette as the paper content, but then I learned that it's too long.

When browsing through the published papers in JOSS, to me it seemed a bit strange that everything was so short and it kind of gave me a feeling of "very minimum work needs to go into this" which I do realize is the core value of JOSS, but it still felt a little bit too amateur to be taken seriously. I hope I'm not being too cynical, it's just the honest reaction I had.

I would personally vote to have the option to submit longer papers if the author has the content handy already.

[danielskatz]

If you want to publish a longer paper, there are lots of existing options - see https://www.software.ac.uk/which-journals-should-i-publish-my-software

[daattali]

@danielskatz Thank you. I added my comment because of @arfon 's last comment:

and if we get lots of people asking to submit longer-form pieces then perhaps we could revisit?

So I wanted to voice my support for longer-form. If you guys think this decision is set in stone, then it might be worth mentioning and making it clear that JOSS is by design ONLY for short papers and if you want a longer paper then you can submit to X/Y/Z.

[pjotrp]

Personally I don't see why we should set the limit at the size of a paper. We can encourage an author to shorten a paper - but if there is valuable information in there, who are we to disagree? @arfon do you think JOSS is by design for short papers?

[arfon]

@arfon do you think JOSS is by design for short papers?

Very much so, this is a deliberate decision (see http://joss.theoj.org/about#author_guidelines):

• A list of the authors of the software
• Author affiliations
• A short summary describing the high-level functionality of the software
• A list of key references including a link to the software archive

and...

You can see an example paper here. Given this paper format it is _not_ permitted to write a "full length" paper i.e. one that includes software documentation such as API (Application Programming Interface) functionality, as this should instead be outlined in the software documentation.

As @danielskatz mentioned earlier in this thread, there are already a number of good options for publishing a 'full' paper about software. JOSS' focus is on short abstract/summary-style papers.

[labarba]

Another option for long-form papers is PeerJ CS.
See, for example:
https://peerj.com/articles/cs-68/