Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

draft of data workflow diagram task #1528

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions _data/news.yml
Original file line number Diff line number Diff line change
Expand Up @@ -182,3 +182,7 @@
date: 2024-06-10
linked_pr: 1489
description: We are gradually improving the icons that are in use on the RDMkit by applying our own style. You can discover them throughout the whole website!
- name: "New page: Data workflow diagram"
date: 2024-09-16
linked_pr: 1528
description: This page guides you with capturing your planned data workflow in a diagram. [Discover the page here](data_workflow_diagram).
2 changes: 2 additions & 0 deletions _data/sidebars/data_management.yml
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,8 @@ subitems:
url: /storage
- title: Data transfer
url: /data_transfer
- title: Data workflow diagram
url: /data_workflow_diagram
- title: Documentation and metadata
url: /metadata_management
- title: Ethical aspects
Expand Down
2 changes: 1 addition & 1 deletion pages/data_life_cycle/planning.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ page_id: plan
description: Introduction to data management planning.
contributors: [Siiri Fuchs, Korbinian Bösl, Minna Ahokas, Federico Bianchini, Flora D'Anna]
related_pages:
your_tasks: [compliance, costs, dmp, data_security, dm_coordination, machine_actionability]
your_tasks: [compliance, costs, dmp, data_security, dm_coordination, machine_actionability, data_workflow_diagram]
training:
- name: Training in TeSS
registry: TeSS
Expand Down
56 changes: 56 additions & 0 deletions pages/your_tasks/data_workflow_diagram.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
---
title: Data workflow diagram
contributors: [Vilem Ded]
description: Best practices to capture your planned data workflow in a diagram.
page_id: data_workflow_diagram
related_pages:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
related_pages:
related_pages:
your_tasks: [dmp]

Copy link
Member

@bedroesb bedroesb Sep 16, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Currently we do not allow task pages to be linked to other task pages. Only assmeblies: https://rdmkit.elixir-europe.org/editorial_board_guide#related-pages

dsw:
faircookbook:
---

## Why you should draw a data workflow diagram?
Copy link
Member

@bedroesb bedroesb Sep 16, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think all your solutions fall under why we should have one. Should we not also have a section about how?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not a native speaker, but "Why should you draw a data workflow diagram?" sounds better to my ears, but this can be on me!


### Description

Creating a data workflow diagram for your research project greatly enhances your data management process. While Data Management Plans (DMPs) can span tens or even hundreds of pages, a diagram offers a more concise and accessible way to represent your workflow. This visual approach helps bridge the gap between partners who may have varying perceptions and levels of understanding, ensuring everyone is aligned. Diagrams make it easier to identify potential issues by highlighting undocumented data sources or destinations that might otherwise go unnoticed in a lengthy document. Additionally, these visual representations are invaluable during discussions and planning sessions, sparking deeper conversations and encouraging collaboration. A well-crafted workflow diagram also boosts the engagement of less-involved partners or stakeholders, giving them a clear and intuitive way to contribute to the planning process.

### Considerations

* Even a simple diagram can significantly improve clarity and communication, but it's essential to first consider the complexity of the workflow. If the process is straightforward and can be easily described in a single paragraph, a diagram might not be necessary. However, for more complex workflows, a diagram is invaluable for identifying steps, dependencies, and potential issues.
* If your workflow can be fully explained in a short, detailed paragraph, then a diagram may not add much value. However, for processes with multiple steps, data sources, or stakeholders, a diagram helps break down complexities and ensures everyone has a shared understanding.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a repetition of the first point. Can they be merged into one?

Suggested change
* If your workflow can be fully explained in a short, detailed paragraph, then a diagram may not add much value. However, for processes with multiple steps, data sources, or stakeholders, a diagram helps break down complexities and ensures everyone has a shared understanding.
* Even a simple diagram can significantly improve clarity and communication, but it's essential to first consider the complexity of the workflow. If the process is straightforward and can be easily described in a single paragraph, a diagram might not be necessary. However, for more complex workflows with multiple steps, data sources, or stakeholders, a diagram is invaluable for identifying steps, dependencies, potential issues and ensuring everyone has a shared understanding.

* The more complex the workflow, the more time and effort it will take to create and update the diagram. It’s important to plan carefully and ensure that the time invested in diagram creation and updates is manageable and that your contribution is clearly recognized.
* A diagram can include sensitive or confidential information, so be cautious about sharing it publicly. Ensure that proper security measures are in place if the diagram contains details that should remain private.
* Be aware that diagrams can reveal critical details that could be exploited by attackers, such as system vulnerabilities or data access points. Make sure any workflow diagram that includes sensitive information is properly protected to prevent security breaches.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again a repetition with the previous point. Could they be merged?

Suggested change
* Be aware that diagrams can reveal critical details that could be exploited by attackers, such as system vulnerabilities or data access points. Make sure any workflow diagram that includes sensitive information is properly protected to prevent security breaches.
* A diagram can include sensitive or confidential information or reveal critical details that could be exploited by attackers, such as system vulnerabilities or data access points. So be cautious about sharing it publicly. Ensure that appropriate security measures are in place and such information is properly protected to prevent security breaches.

* While a diagram is a helpful tool, it is usually not legally binding without a formal, written description of the workflow. It’s good practice to complement your diagram with a full textual annex to ensure the process is well-documented and understood.
* Content of the diagram will depend on many factors. Its good practice to start with definition of the targeted audience (project partners, data managers, funders, public) and main purpose (capturing life of project data, clarification of data protection framework​, description of pre-processing steps). Based on the targeted audience and purpose, you can then more precisely define the scope of your diagram, e.i what (not) to include. These can be physical assets and entities (partners/people, storage locations, instruments, datasets, documents) or logical elements of your project (processes, data types, partner roles, ...).
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe "i.e. = id est, or 'that is'" ?

Suggested change
* Content of the diagram will depend on many factors. Its good practice to start with definition of the targeted audience (project partners, data managers, funders, public) and main purpose (capturing life of project data, clarification of data protection framework​, description of pre-processing steps). Based on the targeted audience and purpose, you can then more precisely define the scope of your diagram, e.i what (not) to include. These can be physical assets and entities (partners/people, storage locations, instruments, datasets, documents) or logical elements of your project (processes, data types, partner roles, ...).
* Content of the diagram will depend on many factors. Its good practice to start with definition of the targeted audience (project partners, data managers, funders, public) and main purpose (capturing life of project data, clarification of data protection framework​, description of pre-processing steps). Based on the targeted audience and purpose, you can then more precisely define the scope of your diagram, i.e. what (not) to include. These can be physical assets and entities (partners/people, storage locations, instruments, datasets, documents) or logical elements of your project (processes, data types, partner roles).

* Same as DMP, the diagram is a living resource and should be updated as the research project progresses.

### Solution

* Start with simple top level diagram​. Share it and get feedback on what can be refined.

* You can follow these steps.
1. List all assets.
2. List all partners and actors​.
3. List all processes​.
4. Define data sources​ - instrument, patient, collaborator, lab, ...
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Style guide suggests to avoid 'etc.' unless really necessary.

Suggested change
4. Define data sources​ - instrument, patient, collaborator, lab, ...
4. Define data sources​ - such as instrument, patient, collaborator, lab.

5. Define final data locations (sinks)​ - archives, repositories, external processes, ingestion zones, ...
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
5. Define final data locations (sinks)​ - archives, repositories, external processes, ingestion zones, ...
5. Define final data locations (sinks)​ - for example, archives, repositories, external processes, ingestion zones.

6. Start drawing visual elements representing the outer interface (sources and sinks) and move inwards.
7. Iteratively refine the diagram based on items which were not yet included.

* Too complex diagrams can be split. Define sub-processes and detect input/output flows /interface).
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* Too complex diagrams can be split. Define sub-processes and detect input/output flows /interface).
* Too complex diagrams can be split. Define sub-processes and detect input/output flows or interfaces.

* Various attributes of visual elements can be mapped to aesthetics. These can be:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* Various attributes of visual elements can be mapped to aesthetics. These can be:
* Various attributes of visual elements can be mapped to aesthetics. These can be:

* square for processes performed automatically vs. rectangle for processes performed manually (shape).
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Formatted the list according to the style guide and changed to singular to match the rest of the list.

Suggested change
* square for processes performed automatically vs. rectangle for processes performed manually (shape).
* square for process performed automatically vs. rectangle for process performed manually (shape);

* red line for sensitive data flow vs. blue for non-sensitive data (line color).
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* red line for sensitive data flow vs. blue for non-sensitive data (line color).
* red line for sensitive data flow vs. blue for non-sensitive data (line color);

* color, fill, border, ...​
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* color, fill, border, ...​
* color, fill, border.

* Be consistent in mapping of aesthetics. For example, instead of using fill colors to depict encryption status (red vs blue) and collaborator's roles (green for researchers vs blue for contractors), you can use small key icon for the encryption status (shape).
* Include legend if the aesthetics is complicated
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* Include legend if the aesthetics is complicated
* Include legend if the aesthetics is complicated.

* If the mapping gets too complicated, include a legend.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Repetition

Suggested change
* If the mapping gets too complicated, include a legend.

* Don't forget to include date of last update, version and your name.

* Source files for the diagrams should be vector based to facilitate portability and reuse. SVG
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* Source files for the diagrams should be vector based to facilitate portability and reuse. SVG
* Source files for the diagrams should be vector based to facilitate portability and reuse. For example, Scalable Vector Graphics (SVG).

* For dissemination, you can use PNG or other
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* For dissemination, you can use PNG or other
* For dissemination, you can use a raster-graphics file format such as Portable Network Graphics (PNG) or other.

* Use vector graphics tool of your preference.
* open source: Draw.io, Inkscape, Libre Office Draw, ...
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* open source: Draw.io, Inkscape, Libre Office Draw, ...
* open source: Draw.io, Inkscape, Libre Office Draw.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would maybe also add urls to these, or add them to the tools table.

* licensed: MS Visio*, Miro.com*,Corel Draw*, MS PowerPoint*
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@vildead what * after software name means?

Suggested change
* licensed: MS Visio*, Miro.com*,Corel Draw*, MS PowerPoint*
* licensed: MS Visio*, Miro.com*, Corel Draw*, MS PowerPoint*.

* Investigate your tool and all features it provides. E.g. Draw.io allows you to host the diagram in Github making it very convenient tool for collaborative editing.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* Investigate your tool and all features it provides. E.g. Draw.io allows you to host the diagram in Github making it very convenient tool for collaborative editing.
* Investigate your tool and all features it provides. E.g. Draw.io allows you to host the diagram in GitHub making it very convenient tool for collaborative editing.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe we make use here of {% tool "github" %}

Loading