elixir-europe / rdmkit

ELIXIR Data Management Toolkit - Find the answers to your research data management questions here.

RDMkit

The ELIXIR Research Data Management Kit

RDMkit is an online guide containing good data management practices applicable to research projects from the beginning to the end. Developed and managed by people who work every day with life science data, RDMkit has guidelines, information and pointers, organised in many different ways to help you with problems throughout the data’s life cycle.

You will find helpful advice for where you are in the data’s life cycle (from collection planning to archiving) and for what kind of data problem you may have. Our up to date tools and resources lists are smartly cross-linked to these guidelines. We also have tailored help for different areas of biology and their specialist data types, and real examples of how tools have been assembled to support data management.

Our goal is to make data management easier for you, and to help you make your data FAIR - Findable, Accessible, Interoperable and Reusable.

Contribute

RDMkit is an open community project, and you are welcome to join us! The content of the material is developed in Markdown and a templating system (Jekyll) is used to format the Markdown pages and generate a website at (https://rdmkit.elixir-europe.org/).

Do you want to help with this project? Please check out following pages for more information:

• Code of Conduct
• How to contribute

Do you which to contact the editors of this project? Use [email protected]

If you want to build the website locally, please have a look at our Git tutorial.

RDMkit is an ELIXIR product

ELIXIR is an intergovernmental organisation that brings together life science resources from across Europe. These resources include databases, software tools, training materials, cloud storage and supercomputers. All the ELIXIR National nodes and the special EMBL-EBI node have come to support data management within the Nodes and for data stewards, researchers and institutional data managers. The idea is to support data management at the point of creation and enable data to be "FAIR by Design". The development of a Research Data Management Kit will provide researchers with a strategy to manage their data to international standards.

License

The process documents and data are made available under a CC-BY license. Software are made available under an MIT license. More information about our license can be found on our license page.

Acknowledgements

The RDMkit was supported by ELIXIR-CONVERGE and it is coordinated by ELIXIR Europe and NIH.

Custom icons

We would like to thank Xènia Pérez Sitjà for creating the custom icons for the RDMkit. Her work has added to the visual appeal and usability of our toolkit.

rdmkit's Issues

Incorporate 'Your role' section

I find it odd that the pages in 'Your role' talk about fictional characters (e.g. Janet Brown). Reading the page, I feel they're talking about someone else's problems, and not addressing mine.

Maybe we should remove 'My background' and change 'Common data issues I encounter' to 'Common data issues'. That way the information is more about the role than about one person, and people can relate to it easier. The fictional persona information is useful for internal consumption, to help us understand users better, but I don't know if it's useful on the website.

What do you think?

P.S. Sorry if this has been through lots of discussion already and I missed it!

Applying Bioschemas to the site

What are the bioschemas profiles we should apply to the site?

Create issue templates

At least two templates are needed.

• Request/propose new page
• Fix existing page

Develop the "Style Guide"

The style guide should be written. Ideally by a native English speaker.

Would include advice such as:

• Citing other resources.
• Text style. Use of active voice instead of passive. Avoiding latin abbreviations. Quoting
• Using images and icons. Preferred formats and licenses.
• Cross referencing between multiple pages.

Convert contribution process diagram to draw.io and share with editors

Introduction to data brokering page

What topic do you wish to add?
I would like to write a page on data brokering. it shall be a gentle introduction.... 101

Are there existing pages in the RDM toolkit website related to the requested page?
I have not seen any existing page.

Resources
If there are there resources that could be utilised for writing the new page, please list them below:

Context
If this request is coming from a particular project, domain, or use-case please list them below:

This page will be created as part of CONVERGE exploration.

Bio.tools id in toollist

• Bio.tools id property in toollist
• icon in tools table

Automatic lookup of the resources for FAIRsharing identifiers

Add to the automation script the automatic checking if a name of a resource or tool can be found in FAIRsharing using their API.

Update: latest API under construction and not to be used by the public

Use a proper domain name?

Maybe we want to use a subdomain name like 'rdm-toolkit.elixir-europe.org' (a bit long) or get a separate domain like 'rdm-toolkit.org', or stick with the current url (https://elixir-europe.github.io/rdm-toolkit/).

Automatically synchronize the frontpage sections with the sidepanel

Using the main.yml file defining the sidepanel sections, it would be possible to generate based on this file the frontpage.

Delete "Summary" from all pages

The editorial board would like to delete the "summary" from the metadata in all pages. Is there a way of deleting "summary" in bulk from all pages?

Ensure a consistent colour scheme for the site

Change the current template to ELIXIR colours? Most of the template should remain white so I'm not suggesting a frenzy of orange. The colour scheme should apply to illustrations as well as to the coloured elements on the page. Main ELIXIR colours:

• Orange: #f47d21
• Dark blue: #023452

There are also lighter blues and a green (BEWARE: it looks hideous with the orange). Finally there is grey as well. Can post the hex codes for them all if required.

ensure (local) legal requirements

Explore addition of requirements such as:

• imprints (e.g. German law ?)
• privacy statement (needed for GDPR ? What does GitHub track?)
• Accessibility statement
• Cookie policy?

tagging of pages

where do we list the possible tags ? how do we structure the tags themselves ?
the high level structure will have tags (data life cycle stages, personas, functional areas)
but more detailed ones might be needed

Decide on a RDM life cycle design

We agreed to have a RDM life cycle diagram on the home page. I've had a look at some designs and put them in a doc. Note that some are just generic 'life cycle' diagrams and don't relate to data: https://docs.google.com/document/d/1k8WR3ZXt0T4uNB1EAsmR1h1MJL-SEfJIvODnKiYIHE4/edit?usp=sharing
Feel free to comment or add more.

We need to bear in mind:

• #6 i.e. the diagram needs to be used in miniature as a navigation aid as well.
• Icons might be nice (not all designs include them).
• The site will probably not contain many attractive photographs and illustrations, so maybe a more colourful diagram would be better? We could colour-code sections of the site and cheer up the text-heavy pages!
• We can make the diagram interactive - Jacek and I got one working last week, and Jacek has found a neat way of embedding the SVG without cluttering up the home page code.

**EDIT: ** this is a separate issue to the life cycle diagram content, dealt with here: #28.

Attribution of contributors : how ?

In The Turing Way this is detailed in the
https://github.com/alan-turing-institute/the-turing-way/blob/master/GOVERNANCE.md

Is this the default naming for this ? As I do not associate governance with authorship e.g.
We do want to explain how we recognise contributions

Agree on the terms to use in the RDM life cycle diagram

RDM life cycle diagrams differ in what they call the stages. See designs 1, 3, 8, 9, 10 here: https://docs.google.com/document/d/1k8WR3ZXt0T4uNB1EAsmR1h1MJL-SEfJIvODnKiYIHE4/edit#

We need to agree what the terms will be. @OlivierCollin has a proposal in this PR: #13.

Perhaps the criteria should be:

• Which words will the users most recognise (user personas)?
• Which areas do they have problems in? e.g. some cycles end in 'Destroy', others 'Archive' and others 'Preserve'. Which of these does a user most want to know about?

Renaming "Examples" to "Tool Assemblies"

Description
I would suggest to rename "Examples" to "Tool Assemblies" to make it more clear.

Inconsistent fonts

The font used for the top left bookmark "ELIXIR RDM Toolkit" is recognisably different from the other fonts used on the site.

Adding custom GitHub labels for Issues and PRs

Useful to have labels to categorise issues, next to the default that GitHub provides ?

Suggestions (inspired by the Turing way):

Project management
Community
Tools
Typo-fix (Fix a typo or a broken link, make the project better)
Work-in-progress
Idea-for-discussion (This can be used for inviting discussion from collaborators or community in general)
Outreach
UI-UX
Personas

Linking the tags in the toollist to pages

A proposal by @martin-nc in PR #51 , we could make the tags in the toollist clickable. But than we should decide on the tags and to which page they refer to.

Styling refinements

• Center data life cycle diagram
• Fix font in data life cycle diagram
• maximum width of tables same as main text
• first column with tool names wider so name fits
• 4 buttons home screen wider
• remove/remap edit me button in all tools page
• margin problem buttons sidepanel, small shift in sublevel when opening toplevel
• take away link icons in 4 buttons home page
• color of H3 titles
• better spacing between sidenav
• fixing problem with icon in the life cycle diagram (make them non clickable)
• fixing html ugliness in generated pages
• fix white space under footer on index page because of the unfolding flexboxes
• Dots of lists in same blue as H2
• better image margins in content

Test-drive contribution process

We need at least one person to test the pages describing how to contribute.

Search results are not clickable in mobile mode

In mobile mode or reduced window size, the search results are not clickable

Steps to reproduce the behavior:

1. resize the window of your browser until the hamburger menu appears
2. go to the hamburger menu
3. type something in the searchbox
4. try to click on the results

tested on edge windows (chrome) and android

Make a 'how to add a tool' guide

Editorial board - editor in chiefs - CODEOWNERS

Set up the editorial board in GitHub (Team?)
Aim is to assign reviewing of new content to a group of people to ensure consistency across the site

Design tweak suggestions

I've got a few suggestions to improve the design of the site. They're just minor tweaks, so I'll put them together here:

1. Font size: the Bootstrap font size for body text translates to 15px. This is a bit small as a browser's default size usually translates to 16px. I wonder if we can increase it slightly? I'm assuming changing the base rem figure will also adjust headings and line height in proportion. If not, we might have to do that manually.

2. Footer margin: the text at the end of the page comes very close to the footer. Can I suggest giving the footer a top margin of 4rem or so? On the home page the footer jumps when the last drop-down opens, so as a quick fix we can add more margin on the footer there.

3. Summary box: if a paragraph follows the summary box then it's quite close to the box (see https://rdm.elixir-europe.org/style_guide.html). Perhaps we can increase the top and bottom margin a bit (2.5em)?

4. Link icons: I suggest we remove the links on headers entirely. I don't understand why you would want to click on something to go to the place you've just clicked! Also, I don't think we need the external link icons. They appear on links to the GitHub repo, when really the GitHub repo isn't 'external'. It's to do with the website.

5. Heading spacing: I suggest that <h3> and <h4>s should have less margin so that they form a group with the main subheadings (<h2>s). See https://rdm.elixir-europe.org/collecting, where "Finding existing data" is floating by itself. Maybe use sibling selectors like: h2 + h3 and h3 + h4 so we can target the headings that are followed by subheadings.

6. Search box: I think 'search...' should start with a capital "S".

@bedroesb I can do all these if you like, if everyone is happy with them. I just wanted to put them out for discussion first.

Add PR template and CONTRIBUTING.md

https://docs.github.com/en/github/building-a-strong-community/creating-a-pull-request-template-for-your-repository

CONTRIBUTING.md should reference the licenses for content (CC-BY) and for infrastructure (MIT).

Branding - acknowledgement grants

Which projects / institutes do we need to acknowledge ?
Where and how do we do this ? About page ? Logos on home page ? ELIXIR in template so on each page ?

Fix GitHub signup link

The current link used for GitHub sign-up on the "Github way" page is pointing a place describing various GitHub pricing options. It could be better if we used the link that is simpler to follow for end-users https://github.com/join

Contact email for the toolkit

Do we need a contact email specifically for the toolkit? I can create one like [email protected] if that is useful. It will be a forwarding email, so it will forward to the WP mailing list or to individuals' addresses. It's up to you. You won't be able to send from this address, that's all.

Sorry if there already is an address!

How to contribute

Inspiration

https://github.com/alan-turing-institute/the-turing-way/blob/master/CONTRIBUTING.md
https://fairplus.github.io/the-fair-cookbook/Contributing.html

From discussions:
Three contributor pathway levels
Upper - using github directly, using markdown templates, assigning tags, pull requests to notify editors
Middle - using googledoc templates, simple raising issues and notifying editors, simple markdown add to pre-existing pages
Lower - using googledoc templates, emailing editors ro submitting a notification through a form.

Writing editorial guide

Topics that cross my mind:

• Copying template files

• Adding links to the sidebar

• Adding people to the contributing list

• Preserving the style and code conduct

• Tagging pages

• Using the tool/resource list

• Github handiness

  • Working with branches

  • Github actions

  • Labeling issues and pull requests

  • Linking issues to pull requests

Merge tools and resources tables

@bedroesb The editorial board decided to DO NOT separate tools and resources. We would like to have only ONE table with "tools and resources" together.

'Contributing' feedback

I've had a go at the Contribute pages and here is my feedback.

Contribute page:

• - Do we need the summary at the top? I don't think so. I find it distracting because it says "please follow the links on the left", and so discourages you from reading the page!
• - Flow diagram: it would be nice if this was in the brand colours, and the boxes were links (at least to the two ways of contributing). I could have a go at redrawing it but not sure if I'll have time before the hackathon.

GitHub way page:

• I got lost with all the links in this page.
  • I'd suggest removing the 'Go the RDM toolkit website' links, because you are already on the website! I'd make the link go to where people need to go (the issues page etc) and maybe mention "You can also get to this page using the 'GitHub' link in the header of this site".
  • I found the links to the GitHub documentation pages confusing. 'Preview here' didn't make sense to me: what am I previewing? I hadn't done anything to preview. Also phrases like "Open a [link]Draft pull request[/link]" suggest you should click on the link to open a draft pull request, but you don't. You get taken to a GitHub documentation page. You could change the link text to "See the GitHub documentation" but I think it's better to remove links to GitHub documentation altogether. Perhaps there can be a section at the end with links to it. We need people to follow one simple path: we open the issues page in a new tab for them in the first link, and then we give them no more links. They need the documentation page open plus the issues page open, and no more links to muddle them and take them away from the task in hand.
  • Little screenshots of the buttons would be good but I don't know if there will be time before the contentathon.
  • I didn't know what a 'Demo page' was. I couldn't think what it would be demonstrating. I'd call the demo page a 'Formatting guide' or 'Code reference' page.

Google Doc way

• I wonder if we need the diagram at the top? It feels like an internal document to me. If people are going to that page because they are frightened of GitHub then perhaps the diagram will frighten them as well! It looks quite complicated. Perhaps we need the process to look simple?
• What does someone do if they only want to suggest a small change to a page? The Google Doc way suggests that it's for large text inserts, like new pages, rather than editing existing pages.

Anyway, those were just my thoughts. I'll see if I can get other people to try it all out.

Contributors on page level

Add the contributors property to the meta data of the page and visualize them

Guidance on location in the website

make use of the tagging of a page (e.g. planning stage of the life cycle) and show a visual clue on the page that details this

Flowcharts not readable

Describe the bug
Text in flow charts in the Github way and google doc way pages are not readable.

Expected behavior
It should be possible to click on the chart to have a zoomed-in view.

Additional context
Reported by @smza

(Knowledge) Resources

We discussed parallel to the tool list to have a list of (knowledge) resources e.g. site to read up on a specific topic or specifications. This could have links to fairsharing (analogous as bio.tools for the tools)

Fixing sitemap.xml

https://rdm.elixir-europe.org/sitemap.xml is having an error

Trial for a adding New content

Write about the topic you are proposing
This is about the testing the contractors guide

Are there existing pages in the RDM toolkit website related to the requested page?
No there are related pages existing on the website.

Resources
If there are there resources that could be utilised for writing the new page, please list them below:

Context
If this request is coming from a particular project, domain, or use-case please list them below:

Create a template for Team 4's best practice guidelines

We need to have a nice template for Team 4's best practice guidelines: https://drive.google.com/drive/folders/1Nx4ZWYQVnGeZ5etHoFZ3_ftB66Ru7o5q

This will allow us to see how they work as web pages, and to start filling out the content of the site.

Note: Remember that 'practice' is a noun and 'practise' is a verb! So 'We follow best practices' vs 'I practise the piano'.

Recruit editorial board

We need volunteers for the editorial board

• for the overall site
• for major sections

Landing page

What should be on the first page ? Different layout ?
Brief description of the goals
Structure of the information (tiles?)

Editorial board - editors for major section

2 editors for each major section to review content changes and ensure consistency
How to set this up in GitHub ?

Adapt Code of Conduct

• Replace references to Turing Way and committee member names
• Cite the original document URL
• Compare with ELIXIR CoC
• Set up/use an email address that can be used to report CoC violations

Template for functional areas/ your problem

At this moment there is no template for functional areas. Do we need one? maybe a generic one that people can just copy around and with some basic guides

Ways of working - Governance

Add a page to detail how the process works for adding content and ensuring consistency (editorial board etc)

Inspiration: https://github.com/alan-turing-institute/the-turing-way/blob/master/ways_of_working.md

This documents outlines expectations and responsibilities of project members and contributors of ELIXIR Data Management Toolkit with regards to working on the project.

Should this be a separate document or part of 'how to contribute'?
Is 'ways of working' a good name ? Does 'governance' fit better ?

Support for multiple templates

Based on a tag in the metadata of the markdown file, another layout/template is applied.

About page

Page to clarify the context in which this was made, acknowledging funding etc.