Refactor of contribute pages #1437
Conversation
improve readability and clarity
|
|
||
| ## Ownership of content | ||
| Contributors will be shown at the bottom of each page and on the main [contributors page](https://rdmkit.elixir-europe.org/contributors). if listed in the metadata of the markdown file. All contributors will also be displayed on the. If you want to link your GitHub account, ORCID or email address, please add your name and corresponding information to the [CONTRIBUTORS file](https://github.com/elixir-europe/rdmkit/blob/master/_data/CONTRIBUTORS.yaml). |
There was a problem hiding this comment.
All contributors will also be displayed on the.
This sentence does not seem to be complete
There was a problem hiding this comment.
I'm guessing that's a fragment that shouldn't be there. Maybe the passage should read:
Contributors will be shown at the bottom of each page and on the main contributors page if listed in the metadata of the markdown file. If you want to link your GitHub account, ORCID or email address, please add your name and corresponding information to the CONTRIBUTORS file.
There was a problem hiding this comment.
I'm guessing that's a fragment that shouldn't be there.
I think you are right.
If you want to link your GitHub account, ORCID or email address, please add your name and corresponding information to the CONTRIBUTORS file.
I never realised adding your information to the CONTRIBUTORS yaml was not mandatory. I think we should require some information (at least the ORCID) since we are promoting best practices. Any thoughts @bedroesb?
There was a problem hiding this comment.
Can we assume everyone has a ORCID?
There was a problem hiding this comment.
Can we assume everyone has an ORCID?
It would be my assumption, but maybe I am living inside a bubble. ORCID is typically required by scientific journals to publish, so at least there is a strong push for scientists to create one anyway. (I created mine 7 years ago)
Co-authored-by: Federico Bianchini <[email protected]>
Co-authored-by: Federico Bianchini <[email protected]>
Co-authored-by: Federico Bianchini <[email protected]>
Co-authored-by: Federico Bianchini <[email protected]>
Co-authored-by: Federico Bianchini <[email protected]>
pages/contribute/github_way.md
Outdated
| 1. Editors publish your content. | ||
| 2. Click “Issues” in the top menu bar and look at the existing issues. See if your idea or suggestion is already being discussed. | ||
| * If an issue exists, comment and let people know if you want to contribute. | ||
| * If no relevant issue exists, create a new issue by clicking the green “New issue” button on the right and choosing one of the issue templates. You can find more information on creating issues in the [GitHub documentation](https://docs.github.com/en/github/managing-your-work-on-github/creating-an-issue). |
There was a problem hiding this comment.
...and choosing one of the issue templates.
...and choose one of the issue templates.
"Choose" needs to be imperative, I think, like "create" before it.
There was a problem hiding this comment.
I think the intended coordination is between "clicking" and "choosing", not between "create" and "choosing" (create by clicking and choosing).
There was a problem hiding this comment.
@martin-nc do you agree here with @bianchini88 ?
There was a problem hiding this comment.
Oh, by the time I'd got to "choosing" I'd forgotten about "create"! I suppose you could say:
If no relevant issue exists, create a new issue: click the green “New issue” button on the right and choose one of the issue templates.
Or just leave it as it is.
|
|
||
| ## Ownership of content | ||
| Contributors will be shown at the bottom of each page and on the main [contributors page](https://rdmkit.elixir-europe.org/contributors). if listed in the metadata of the markdown file. All contributors will also be displayed on the. If you want to link your GitHub account, ORCID or email address, please add your name and corresponding information to the [CONTRIBUTORS file](https://github.com/elixir-europe/rdmkit/blob/master/_data/CONTRIBUTORS.yaml). |
There was a problem hiding this comment.
I'm guessing that's a fragment that shouldn't be there. Maybe the passage should read:
Contributors will be shown at the bottom of each page and on the main contributors page if listed in the metadata of the markdown file. If you want to link your GitHub account, ORCID or email address, please add your name and corresponding information to the CONTRIBUTORS file.
Yes! |
|
Yes, I think @bianchini88 is right about the prerequisite bit. We don't need to mention a negative prerequisite. I mean, you can still use the GitHub method even if you do have technical knowledge! I also think a little knowledge of markdown is a prerequisite, and a link to the cheatsheet might be handy here. So the bullet point could be "Basic knowledge of markdown. All you need to know is in our markdown cheatsheet". As for screenshots, I've found that most people like them in instructions (and so do I!). They just confirm you are looking in the right place. In the new "Start editing" section, it says:
I think we might need to say where the icon is, like "...next to the page title". |
|
@bedroesb I agree with everything @martin-nc is stating above. I am also wondering whether it is the case to add a link to https://rdmkit.elixir-europe.org/page_metadata#possible-metadata-attributes-of-a-page. |
Update contribute.yml
|
After a last round of feedback I:
|
|
@bianchini88 and @martin-nc for completeness! |
|
At the top of this page what do we mean exactly with
? |
We have never discussed whether adding this information should be mandatory or not. I would argue that all people have an institutional email address and most people have an ORCID, as this information is also required for e.g. publishing. So I would make these mandatory and the GitHub account optional. |
(here) |
|
Other than the few minor points I raised above, I am happy with this PR, @bedroesb. |
What do you think of:
|
I will change the phrasing, but it will still be a "soft" requirement. |
Well spotted, I've updated it! |
|
@bianchini88 I think I've tackled your comments, let me know what you think |
|
@bedroesb Now that I am looking at this again, I have another comment
2 out of 3 points have nothing to do with "consistency and efficiency". You can maybe just get rid of that and rephrase it. PS I am on leave this week, so expect slow responses. |
|
@bianchini88 No problem, I trimmed the sentence. |
This PR includes the wording of the contribute pages for the three different ways available.
It also includes correction of typos in other pages of this section.
Preview here