add guidelines on research code in User Guide#7717
Conversation
|
I suggest @poikilotherm, @jggautier, @pdurbin have a look at the text. PS: I expect that we'll have updates on the section with time, but this should be a viable start. |
|
@atrisovic, I've reviewed this addition to the guides. I think it's great and is very clear even to someone like me with limited experience publishing research code. I wouldn't be able to contribute anything substantive but could contribute some minor prose style changes. |
|
It may be out of scope for this PR; but it might be worth considering recommending that depositors provide (at least minimal) information about the execution environment they used to run the code. |
pdurbin
left a comment
pdurbin
left a comment
There was a problem hiding this comment.
I didn't review the content yet but left some suggestions to capitalize headings to match our house style.
| - Data File Citation (currently in either RIS, EndNote XML, or BibTeX format); | ||
| - All of the above, as a zipped bundle. | ||
|
|
||
| Research code |
There was a problem hiding this comment.
| Research code | |
| Research Code |
Our "house style" is to capitalizing all headings.
| - Consider testing your code in a clean environment before sharing it, as it could help you identify missing files or dependencies. | ||
| - Consider providing notes (in the README) on the expected code outputs or adding tests in the code, which would ensure that its functionality is intact. | ||
|
|
||
| General guidelines |
There was a problem hiding this comment.
| General guidelines | |
| General Guidelines |
atrisovic
force-pushed
the
docs-research-code
branch
from
867a70f to
b569c3e
Compare
djbrooke
left a comment
djbrooke
left a comment
There was a problem hiding this comment.
Thanks @poikilotherm for the tag and nice work @atrisovic ! It looks like there are some other people tagged so I won't approve quite yet, but consider this a 👍 from me.
|
Fine with me as well, nice first steps! |
pdurbin
left a comment
pdurbin
left a comment
There was a problem hiding this comment.
The content looks good. I believe I have found a few formatting errors. I didn't test them locally.
atrisovic
force-pushed
the
docs-research-code
branch
from
f0c12ae to
b569c3e
Compare
poikilotherm
left a comment
poikilotherm
left a comment
There was a problem hiding this comment.
Thanks @atrisovic for getting this party started. I have a few thoughts, but no show stoppers.
|
I incorporated all suggestions and tested the page locally. I think it's ready to be merged 😄 |
Removing lines 196-197, 208-209 to resolve warning: Warning, treated as error: /home/worker/workspace/guides.dataverse.org/doc/sphinx-guides/source/user/dataset-management.rst:200: SEVERE: Title level inconsistent:
8 participants
What this PR does / why we need it:
It adds guidelines on research code in the User Guide. We need it because we don't have guideline on that so far.
Suggestions on how to test this:
All links should work. The text should be understandable to a layperson.
Does this PR introduce a user interface change? If mockups are available, please link/include them here:
No.
Figure: