draft of data workflow diagram task #1528
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
vildead
requested review from
wittigue,
floradanna,
smza,
marikapop,
Nazeeefa and
diana-pilvar
as code owners
|
I still plan to find nice example of such a diagram (maybe even two - one simple and one complex) Also, I am not sure the page fits to RDMKit or it would be better to have it in FAIRCookbook (or both to some extend). |
marikapop
reviewed
Sep 16, 2024
| ### 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. |
There was a problem hiding this comment.
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. |
| * 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. | ||
| * 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. |
There was a problem hiding this comment.
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. |
| * 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. | ||
| * 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, ...). |
There was a problem hiding this comment.
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). |
| 1. List all assets. | ||
| 2. List all partners and actors. | ||
| 3. List all processes. | ||
| 4. Define data sources - instrument, patient, collaborator, lab, ... |
There was a problem hiding this comment.
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. |
| 2. List all partners and actors. | ||
| 3. List all processes. | ||
| 4. Define data sources - instrument, patient, collaborator, lab, ... | ||
| 5. Define final data locations (sinks) - archives, repositories, external processes, ingestion zones, ... |
There was a problem hiding this comment.
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. |
| * 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 | ||
| * For dissemination, you can use PNG or other |
There was a problem hiding this comment.
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. |
| * Source files for the diagrams should be vector based to facilitate portability and reuse. SVG | ||
| * For dissemination, you can use PNG or other | ||
| * Use vector graphics tool of your preference. | ||
| * open source: Draw.io, Inkscape, Libre Office Draw, ... |
There was a problem hiding this comment.
Suggested change
| * open source: Draw.io, Inkscape, Libre Office Draw, ... | |
| * open source: Draw.io, Inkscape, Libre Office Draw. |
There was a problem hiding this comment.
I would maybe also add urls to these, or add them to the tools table.
| * For dissemination, you can use PNG or other | ||
| * Use vector graphics tool of your preference. | ||
| * open source: Draw.io, Inkscape, Libre Office Draw, ... | ||
| * licensed: MS Visio*, Miro.com*,Corel Draw*, MS PowerPoint* |
There was a problem hiding this comment.
@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*. |
| * Use vector graphics tool of your preference. | ||
| * open source: Draw.io, Inkscape, Libre Office Draw, ... | ||
| * 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. |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
maybe we make use here of {% tool "github" %}
| contributors: [Vilem Ded] | ||
| description: Best practices to capture your planned data workflow in a diagram. | ||
| page_id: data_workflow_diagram | ||
| related_pages: |
There was a problem hiding this comment.
Suggested change
| related_pages: | |
| related_pages: | |
| your_tasks: [dmp] |
There was a problem hiding this comment.
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
bedroesb
reviewed
Sep 16, 2024
| faircookbook: | ||
| --- | ||
|
|
||
| ## Why you should draw a data workflow diagram? |
There was a problem hiding this comment.
I don't think all your solutions fall under why we should have one. Should we not also have a section about how?
There was a problem hiding this comment.
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!
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.