Codeberg/Documentation
42
199
Fork
You've already forked Documentation
161

Citable Code #81

Merged
n merged 4 commits from ivan-paleo/Documentation:citable-code into master 2020年09月30日 12:26:09 +02:00
Contributor
Copy link

Added some details on how to make your code (repo) citable.
As usual, open to comments and feedback!

Added some details on how to make your code (repo) citable. As usual, open to comments and feedback!
lhinderberger left a comment
Copy link

What an interesting topic - thank you for introducing it and writing this great article on the topic :)

As usual, you'll find a few remarks below:

What an interesting topic - thank you for introducing it and writing this great article on the topic :) As usual, you'll find a few remarks below:
@ -0,0 +3,4 @@
key: CitableCode
title: Citable Code
parent: Collaborating
order: 3
Contributor
Copy link

For articles in sections that are not a step-by-step guide, let's not use order.

That makes it easier to find articles in the menu once alphabetical sorting is implemented -> #85.

For articles in sections that are not a step-by-step guide, let's not use `order`. That makes it easier to find articles in the menu once alphabetical sorting is implemented -> #85.
ivan-paleo marked this conversation as resolved
@ -0,0 +6,4 @@
order: 3
---
The easiest way to share your code is obviously to send/post the URL of your repository. But this is not really viable in the long run becaue URLs can change.
Contributor
Copy link

Wording suggestions:

  • Share -> refer to your code
  • Let’s drop "Obviously" (this article describes what’s wrong with "obviously": https://css-tricks.com/words-avoid-educational-writing/) :)
  • Second sentence: "But if you need to reliably refer to a specific version of your code in the long run, for example for scientific writing, this is not really viable, because URLs can change."
Wording suggestions: - Share -> refer to your code - Let’s drop "Obviously" (this article describes what’s wrong with "obviously": https://css-tricks.com/words-avoid-educational-writing/) :) - Second sentence: "But if you need to reliably refer to a specific version of your code in the long run, for example for scientific writing, this is not really viable, because URLs can change."
ivan-paleo marked this conversation as resolved
@ -0,0 +19,4 @@
![release](/assets/images/collaborating/citable-code/release.PNG)
In the new page, enter a version, select the branch, add a title and a description:
Contributor
Copy link

(削除) Suggested wording "choose a version number for your new release" because "enter a version" suggests the version already exists. (削除ここまで)

(削除) Maybe also "select the branch that contains the code that you want to release" (削除ここまで)

It's even more complicated - its either choosing an existing Git tag or creating a new one from the latest commit.

Right away, I don't know of a more elegant way of writing it though.

~~Suggested wording "choose a version number for your new release" because "enter a version" suggests the version already exists.~~ ~~Maybe also "select the branch that contains the code that you want to release"~~ It's even more complicated - its either choosing an existing Git tag or creating a new one from the latest commit. Right away, I don't know of a more elegant way of writing it though.
Author
Contributor
Copy link

I think that your suggestion is still better than what I wrote. In any case, it constitutes a good starting point for future improvements.
Maybe we should consider adding details about releases in a separate documentation article (we would then link to it in this article about citable code).

I think that your suggestion is still better than what I wrote. In any case, it constitutes a good starting point for future improvements. Maybe we should consider adding details about releases in a separate documentation article (we would then link to it in this article about citable code).
Contributor
Copy link

That's a good idea -> I created issue nr. #88 for that

That's a good idea -> I created issue nr. #88 for that
ivan-paleo marked this conversation as resolved
@ -0,0 +23,4 @@
![new-release](/assets/images/collaborating/citable-code/new-release.PNG)
You can either save as a draft, or publish the release already.
Contributor
Copy link

already -> outright

already -> outright
ivan-paleo marked this conversation as resolved
@ -0,0 +34,4 @@
## Download the ZIP archive
If you did create a release, download the ZIP archive of the source code on the `Releases` tab of your repository, as shown in the previous screenshot.
If not, you can simply download the ZIP archive of the repository (see section Clone in [Clone & Commit via Web](/content/git/clone-commit-via-web)).
Contributor
Copy link

Please remove the /content prefix from your link.

Please remove the `/content` prefix from your link.
ivan-paleo marked this conversation as resolved
@ -0,0 +39,4 @@
## Upload the ZIP archive to an online repository
There are many online repositories made specifically for research, e.g. [Zenodo](https://zenodo.org/), [Figshare](https://figshare.com/), [Dryad](https://datadryad.org/), [OSF](https://osf.io/)... Others might be more appropriate for other uses.
Upload the ZIP archive to one of them and follow the steps there to assign a DOI. Be sure that you add the URL of your Codeberg repository in the information of the record on the online repository, so that every one accessing the record can easily find your Codeberg repository (and you!). In general, add as much information as applicable.
Contributor
Copy link

Typo: every one -> everyone

Typo: every one -> everyone
ivan-paleo marked this conversation as resolved
@ -0,0 +41,4 @@
Upload the ZIP archive to one of them and follow the steps there to assign a DOI. Be sure that you add the URL of your Codeberg repository in the information of the record on the online repository, so that every one accessing the record can easily find your Codeberg repository (and you!). In general, add as much information as applicable.
> WIP: An interface between Zenodo and Codeberg is currently being considered. This would make the process smoother.
Contributor
Copy link

Hehe, I threw the idea around, yes - but that's nothing "official" 😉

We should rephrase that to: "It should be possible to write an integration between Codeberg and one of the DOI repositories to make citing code a lot smoother. If you're interested, you may want to have a look at Codeberg/Community#295"

Hehe, I threw the idea around, yes - but that's nothing "official" :wink: We should rephrase that to: "It should be possible to write an integration between Codeberg and one of the DOI repositories to make citing code a lot smoother. If you're interested, you may want to have a look at [Codeberg/Community#295](https://codeberg.org/Codeberg/Community/issues/295)"
ivan-paleo marked this conversation as resolved
@ -0,0 +44,4 @@
> WIP: An interface between Zenodo and Codeberg is currently being considered. This would make the process smoother.
## Share the DOI
Finally, get the DOI from the online repository. This is the permanent URL you can share and use for citation without any risk.
Contributor
Copy link

Let's drop "without any risk" and replace it with "in scientific writing".

That is, because statements like "without any risk" might be interpreted as an implied warranty (which we do not provide).

Let's drop "without any risk" and replace it with "in scientific writing". That is, because statements like "without any risk" might be interpreted as an implied warranty (which we do not provide).
ivan-paleo marked this conversation as resolved
lhinderberger changed title from (削除) WIP: Citable Code (削除ここまで) to Citable Code 2020年09月26日 15:27:52 +02:00
Author
Contributor
Copy link

I have made the changes based on your comments.
I have also added the webP images!

I have made the changes based on your comments. I have also added the webP images!
lhinderberger left a comment
Copy link

Very nice! :) The only thing that needs to be changed as far as I'm concerned is the filename of new-release.PNG -> new-release.png, as in #78. Let's focus the discussion on the solution for the Windows-related filename casing issue in that PR.

Very nice! :) The only thing that needs to be changed as far as I'm concerned is the filename of `new-release.PNG` -> `new-release.png`, as in #78. Let's focus the discussion on the solution for the Windows-related filename casing issue in that PR.
Author
Contributor
Copy link

It should be fixed now. I'll pay attention to that issue next time!

It should be fixed now. I'll pay attention to that issue next time!
lhinderberger left a comment
Copy link

Thanks! :) 👍

This now needs a second reviewer and can then be merged to master.

Thanks! :) 👍 This now needs a second reviewer and can then be merged to master.
n left a comment
Copy link

Looks good except for a small change.

Looks good except for a small change.
@ -0,0 +49,4 @@
Upload the ZIP archive to one of them and follow the steps there to assign a DOI. Be sure that you add the URL of your Codeberg repository in the information of the record on the online repository, so that everyone accessing the record can easily find your Codeberg repository (and you!). In general, add as much information as applicable.
> It should be possible to write an integration between Codeberg and one of the DOI repositories to make citing code a lot smoother. If youre interested, you may want to have a look at Codeberg/Community#295
Contributor
Copy link

We should add a hyperlink to the issue here.

We should add a hyperlink to the issue here.
ivan-paleo marked this conversation as resolved
Author
Contributor
Copy link

Thanks for the review! The hyperlink should be fixed now.

Thanks for the review! The hyperlink should be fixed now.
n merged commit d2bc1a8c6d into master 2020年09月30日 12:26:09 +02:00
n approved these changes 2020年09月30日 12:26:20 +02:00
n left a comment
Copy link

Thanks!

Thanks!
Sign in to join this conversation.
No reviewers
Labels
Clear labels
Codeberg Pages
Issues affecting Codeberg Pages
Documentation Usability
Issues related to using and reading docs.codeberg.org
Forgejo
Good First Issue! 👋
Kind: Bug
Kind: Documentation
Kind: Enhancement
Kind: Feature
Kind: Question
Kind: Security
Licensing
Part: Generator
This is related to the generation of the documentation, not to the content itself
Priority: High
The priority is high
Priority: Low
The priority is low
Priority: Medium
The priority is medium
Reviewed: Confirmed
Something has been confirmed
Reviewed: Duplicate
Something exists already
Reviewed: Invalid
Something was marked as invalid
Reviewed: Wontfix
Something won't be fixed
Status: Blocked
Status: Help wanted
Contributions are welcome!
Status: In progress
Work is in progress
Status: Needs feedback
Feedback is needed
Status: Ready for Review
Work is completed
Status: Review
Review is in progress / Reviewers wanted
Status: Stale
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
3 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
Codeberg/Documentation!81
Reference in a new issue
Codeberg/Documentation
No description provided.
Delete branch "ivan-paleo/Documentation:citable-code"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?