Compare commits

...

18 Commits

Author SHA1 Message Date
6d7f7f3dfa minor correction with citation. 2025-06-05 19:16:45 +02:00
1dd2310caa more refinement. Not much left to polish 2025-06-05 17:34:59 +02:00
dac7b3f039 restructured parts, shortened, linked more software. 2025-06-05 13:10:05 +02:00
6202af618a much more rework. 2025-06-05 09:56:37 +02:00
19ca830585 reworked background structure, linked a lot more. Added Principles. 2025-06-04 10:30:20 +02:00
b4a0e4dc5e updated Readme 2025-06-03 11:40:20 +02:00
8dd32b411b added first try of references for websites & software 2025-06-03 11:21:35 +02:00
c72a3f255c added Review-Template 2025-05-27 12:41:11 +02:00
9793c6450e removed example project from here. 2025-05-15 15:03:32 +02:00
11af56ddf8 step-by-step for usage 2025-05-15 15:03:02 +02:00
0f35cd6a04 fixes #2 2025-05-15 14:55:44 +02:00
3cb8457bc8 fixed reference 2025-05-15 12:38:53 +02:00
a601ada928 added literature 2025-05-15 12:31:54 +02:00
e41d3c4c3e updated literature based on our shared Zotero library. Note that some of the original references seemingly were generated by LLMs and at least partially fictitious 2025-05-15 12:01:12 +02:00
f54c779f9f duplicated .gitlab to main directory for testing and experimenting 2025-05-15 09:21:20 +02:00
89ab2f39c2 added .gitlab-templates 2025-05-15 09:19:34 +02:00
5172700f0b added yaml header where appropiate, added bibtex-example to CITATION 2025-05-14 17:31:58 +02:00
1d5dc729fd Updated README.md for example-project according to meeting. 2025-05-14 17:21:21 +02:00
35 changed files with 2381 additions and 852 deletions

View File

@ -0,0 +1,39 @@
---
# Settings for generating changelogs using the GitLab API. See
# https://docs.gitlab.com/ee/api/repositories.html#generate-changelog-data for
# more information.
categories:
added: Added
fixed: Fixed
changed: Changed
deprecated: Deprecated
removed: Removed
security: Security
performance: Performance
other: Other
include_groups:
- Methodenlabor
template: |
{% if categories %}
{% each categories %}
### {{ title }} ({% if single_change %}1 change{% else %}{{ count }} changes{% end %})
{% each entries %}
- [{{ title }}]({{ commit.web_url }})\
{% if author.credit %} by {{ author.reference }}{% end %}\
{% if commit.trailers.MR %}\
([merge request]({{ commit.trailers.MR }}))\
{% else %}\
{% if merge_request %}\
([merge request]({{ merge_request.web_url }}))\
{% end %}\
{% end %}\
{% end %}
{% end %}
{% else %}
No changes.
{% end %}
# The tag format for gitlab-org/gitlab is vX.Y.Z(-rcX). Releases are always without trailing -...
tag_regex: '^v(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)$'

View File

@ -0,0 +1,26 @@
### Summary
<!-- Summarize the bug encountered concisely. -->
### Steps to reproduce
<!-- Describe how one can reproduce the issue - this is very important. Please use an ordered list. -->
### What is the current _bug_ behavior?
<!-- Describe what actually happens. -->
### What is the expected _correct_ behavior?
<!-- Describe what you should see instead. -->
### Relevant logs and/or screenshots
<!-- Paste any relevant logs - please use code blocks (```) to format console output, logs, and code
as it's tough to read otherwise. -->
### Possible fixes
<!-- If you can, link to the line of code that might be responsible for the problem. -->
/label ~"type::bug"

View File

@ -0,0 +1,90 @@
## Conference Knowledge Sharing Report
### Conference Details
**Name of Conference:** [Conference Name]
**Date:** [Date(s) of Conference]
**Location:** [Location]
**Attendee(s):** [Your Name]
### Summary of Key Points
Provide a high-level summary of the most important takeaways from the conference
sessions you attended.
- **Keynote Highlights:**
- [Key Point 1]
- [Key Point 2]
- [Key Point 3]
- **Session Highlights:**
- [Session Title 1]: [Key Point 1], [Key Point 2]
- [Session Title 2]: [Key Point 1], [Key Point 2]
### Detailed Insights
Offer detailed insights and observations from the sessions. Include personal
thoughts on the implications for your team or organization.
- **Session 1: [Session Title]**
- **Speaker:** [Speaker Name]
- **Summary:** [Brief summary of the session]
- **Insights:** [Detailed insights and key takeaways]
- **Potential Applications:** [How this knowledge can be applied to our work]
- **Session 2: [Session Title]**
- **Speaker:** [Speaker Name]
- **Summary:** [Brief summary of the session]
- **Insights:** [Detailed insights and key takeaways]
- **Potential Applications:** [How this knowledge can be applied to our work]
### Practical Applications
Describe how the new knowledge can be practically applied to improve team
projects, workflows, or strategies.
- **Application 1:** [Description of how to apply the knowledge]
- **Application 2:** [Description of how to apply the knowledge]
- **Application 3:** [Description of how to apply the knowledge]
### Recommended Actions
Suggest specific actions that the team or organization should take based on the
knowledge gained from the conference.
1. **Action 1:** [Detailed description of the action]
2. **Action 2:** [Detailed description of the action]
3. **Action 3:** [Detailed description of the action]
### Additional Resources
Provide links to additional resources, such as session recordings, slides,
articles, or tools mentioned during the conference.
- [Resource 1: Title](URL)
- [Resource 2: Title](URL)
- [Resource 3: Title](URL)
### Follow-Up
Outline any follow-up actions, such as scheduling a presentation, organizing a
workshop, or setting up one-on-one meetings.
- **Presentation:** [Date and Time for a presentation to share knowledge]
- **Workshop:** [Plan for a hands-on workshop if applicable]
- **Meetings:** [List of colleagues to meet with and discuss specific insights]
### Contact Information
Provide your contact information for any further questions or discussions.
- **Name:** [Your Name]
- **Email:** [Your Email]
- **Phone:** [Your Phone Number]
---
_Please review the above information and provide feedback or ask any questions
in the comments section below._

View File

@ -0,0 +1,27 @@
<!--Lightweight issue template to facilitate decision making by using Decision Matrix -->
## Problem to solve
<!--Link to Description of feature (Documentation, Epic, Opportunity Canvas, etc.) -->
## Decision Matrix
<!-- Decision Matrix helps make a decision based on the acceptance criteria defined for the problem. Acceptance criteria should be put into left column, in the order of importance, with clear information if they are required (must-have) or not (nice-to-have). Options to consider should be scored in the right-side columns. To mark option as viable, it should fulfill all required criteria. -->
| Acceptance criteria | Required | Option 1 | Option 2 |
| ------------------- | -------- | ---------------------------------- | ---------------------------------- |
| Criteria 1 | Yes/No | :white_check_mark:/:no_entry_sign: | :white_check_mark:/:no_entry_sign: |
| Criteria 2 | Yes/No | :white_check_mark:/:no_entry_sign: | :white_check_mark:/:no_entry_sign: |
| Criteria 3 | Yes/No | :white_check_mark:/:no_entry_sign: | :white_check_mark:/:no_entry_sign: |
| Criteria 4 | Yes/No | :white_check_mark:/:no_entry_sign: | :white_check_mark:/:no_entry_sign: |
| **Option Viable?** | - | Yes/No | Yes/No |
## Decision due date
<!--Defining due date for decision aligned with our Efficiency value. -->
## Final decision
<!--Filled after the due date and evaluating all options based on acceptance criteria.-->
/label ~"group::" ~"section::" ~"Category:"

View File

@ -0,0 +1,3 @@
If you feel that your issue can be categorized as a reproducible bug or a
feature proposal, please use one of the issue templates provided and include as
much information as possible.

View File

@ -0,0 +1,125 @@
<!-- Use this template as a starting point for deprecations. -->
**A written process alone is unlikely to be sufficient to navigate through many
complexities. Please use this template as guidance with steps to take when
deprecating functionality, but not as an exhaustive list designed to generate
positive outcomes every time. Deprecations are often nuanced in their impact and
the approach needed may not be fully covered in this template.**
---
### Deprecation Summary
_Add a brief description of the feature or functionality that is deprecated.
Clearly state the potential impact of the deprecation to end users._
#### Documentation
- Deprecation notice: [add link](here)
- Migration guidelines: [add link](here)
- etc.
#### Reasons
\_Describe why deprecation of this feature is necessary
- [add links to the documentation](here) - i.e. Decision-Matrix, etc.
### Breaking Change?
<!-- If the change includes removing functionality, which nearly all deprecations do, then it needs to be tracked as a breaking change. If user workflows rely on it to function, then removing it will break them. -->
Does this deprecation contain a breaking change? `Yes / No`
<!-- If yes:
- Add the ~"breaking change" label to this issue.
- Add instructions for how users can update their workflow.
- After creating this issue, add an Internal Note in the comments below to document the pros and cons of this change and why we are choosing to make a breaking change. Answer the following:
- What migration paths are available?
- Describe tradeoffs between the migration paths taking into account customer, financial, technical or operational impact?
- Are there different migration path options for different users? (ex. available for ultimate users, but not free users?)
- Are there external requirements that we need to meet that restrict our available options?
- Consider the information you will also be adding in the "Affected Customers" section - this will impact how you plan for migration alternatives.
-->
<!--
/label ~"breaking change"
-->
### Affected Users
Who is affected by this deprecation: GitLab.com users, Self-managed users, or
Dedicated users? (choose all that apply)
- [ ] GitLab.com
- [ ] Self-managed
- [ ] Dedicated
### Deprecation Milestone
This deprecation will be announced in milestone: `xx.xx` _If this deprecation
has already been announced, include information about when the initial
announcement went out and what follow-up announcements are scheduled._
### Planned Removal Milestone
The feature / functionality will be removed in milestone: `xx.xx`
### Links
<!--
Add links to any relevant documentation or code that will provide additional details or clarity regarding the planned change.
This issue is the main SSOT for the deprecations and removals process. Be sure to link all
issues and MRs related to this deprecation/removal to this issue. This can include removal
issues that were created ahead of time, and the MRs doing the actual deprecation/removal work.
-->
### Checklists
#### Timeline
#### Communication Plan
- DRI Product Manager: `@PM`
An internal slack post and a release post are not sufficient notification for
our customers or internal stakeholders. Plan to communicate proactively and
directly with affected customers and the internal stakeholders supporting them.
Internal Communication Plan
- [ ] Internal announcement plan (timeline for notifications, audience,
channels, etc)
External Communication Plan
- [ ] User announcement plan (timeline for notifications, audience, channels,
etc)
- [ ] Documentation has been updated to mark the feature as `deprecated`. _Add
link to the relevant merge request._
- [ ] On the major milestone:
- [ ] The deprecated item has been removed. _Add link to the relevant merge
request._
- [ ] If the removal of the deprecated item is a
[breaking change](https://docs.gitlab.com/update/terminology/#breaking-change),
the merge request is labeled ~"breaking change".
- [ ] Document the migration plan for users, clearly outlining the actions
they need to take to mitigate the impact of the breaking change.
- [ ] [Add link](here)
#### Labels
<!-- Populate the Section, Group, and Category -->
/label ~group: ~"Category:
- [ ] This issue is labeled ~deprecation, and with the relevant `~group::`, and
`~Category:` labels.
- [ ] This issue is labeled ~"breaking change" if the removal of the deprecated
item will be a
[breaking change](https://docs.gitlab.com/update/terminology/#breaking-change).
<!-- Identifies that this Issue is related to deprecating a feature -->
/label ~"deprecation"

View File

@ -0,0 +1,285 @@
<!-- Title: Design Sprint -->
This template outlines a sample set-up process, activities and deliverables for running a Remote Design Sprint. The specific activities and deliverables should be customized based on your objectives and timeline.
Please refer to the [Remote Design Sprint Handbook page](https://about.gitlab.com/handbook/product/ux/design-sprint/) for additional recommendations.
## Design Sprint Focus
* [ ] Have you [determined that a Design Sprint is appropriate for this project](https://about.gitlab.com/handbook/product/ux/design-sprint/#when-to-opt-for-a-remote-design-sprint)?
_What is the focus of the [Design Sprint](https://about.gitlab.com/handbook/product/product-processes/#remote-design-sprint)? What problem area will you be solving for and who is the target user?_
## Objectives
_What is the objective(s) this Design Sprint will entail?_
<!-- Try to describe the objectives of the Sprint in detail. e.g., "We want to introduce a new feature but we are unsure that we are thinking about the solution from the customer's perspective, and through the Sprint we want to rethink the solution, prototype it and validate it with our customers" or "We are unhappy with the direction of one of our categories and we want to explore new directions with different stakeholders, reach to one solution and test it with users" or "Among the team we have different visions for a specific category and we want to work towards a solution we all support and test it with users". -->
## Outputs
_Select which outputs you want to have at the end of the Sprint._
- [ ] A User testing flow.
- [ ] A Prototype to be tested with users.
- [ ] User testing analysis.
- [ ] (If the solution is viable) An epic or issue that describes the direction in details and the next steps
- [ ] Necessary updates to the Handbook.
## Design Sprint Details
| Start | End |
| ------ | ------ |
| YYYY-MM-DD | YYYY-MM-DD |
| TT:TT PST | TT:TT PST |
**Reference time zone:** All times will be posted in [UTC](https://www.timeanddate.com/worldclock/timezone/utc).
### WHERE
**Zoom link:**
### WHO
- `Name` `gitlab handle` - Facilitator
- `Name` `gitlab handle` - Decider (usually the Product Manager)
- `Name` `gitlab handle` - Co-decider (optional)
- `Name` `gitlab handle` - Sprint team member
- `Name` `gitlab handle` - Sprint team member
- `Name` `gitlab handle` - Sprint team member
- `Name` `gitlab handle` - Sprint team member
- `Name` `gitlab handle` - Sprint team member
- `Name` `gitlab handle` - Sprint team member
- `Name` `gitlab handle` - Co-facilitator (optional)
## Tools
Here is the list of tools for the Sprint preparation, collaboration and documentation. Prior to the Sprint make sure you have access to all of the following:
* **GitLab**<br/>
Each Sprint day outcomes and material will be documented in separate issues under the Design Sprint epic:
* **Kickoff:** (Kickoff Issue Link)
* **Day One:** (Day 1 Issue Link)
* **Day Two:** (Day 2 Issue Link)
* **Day Three:** (Day 3 Issue Link)
* **Day Four:** (Day 4 Issue Link)
* **Mural** (You can join as anonymous but we need to be able to identify input against names, so please create an account beforehand.)<br/>
We will use Mural for most of the Sprint collaboration. Some of the things we will do in Mural:
* Create artifacts like affinity diagrams from participants' input.
* Use post-its to comment on each other's points and to add notes.
* Vote on ideas and solutions.
* Create the first draft of the prototype.
* **The Mural link can be found here:** (Mural Link)
* **Video and/or screen recording tool** (Loom, Quicktime, Zoom or another tool you are using).<br/>
As part of the pre-Sprint homework, you will be asked to record a short Lightning Walkthrough video (don't worry, this will be explained in detail during the Sprint :smile:). You can use any tool you feel comfortable with as long as it can capture your screen, mouse pointer, and audio.
* **A4/Letter-sized paper (preferably white, blank), Sharpies/Pens** (Please don't use a pencil because it doesn't create enough contrast for photos).<br/>
Day 2 of the Sprint involves some (async) ideation via sketching so you will need a writing utensil (Sharpies are preferred because they force you to draw at a lower fidelity because the small details aren't necessary at this point) and some paper. This is the most fun part of the Sprint where you get into a design thinking mindset and can appeal to your creative self. Don't worry, it's not about artistry, it's about ideas and collaboration. It'll be fun!
* **Camera (phone or other) or scanner**<br/>
You will need to upload sketches as images for the facilitator to prepare the material before the next sync meeting. You can take a photo with your phone or use a scanner if available.
* **Post-it notes (Optional)**<br/>
If you enjoy taking notes using Post-it notes make sure you have some of them as well. The upside is that they will make you feel more like you are in a workshop and will help the ideas flow (I find that typing is distracting while ideating). The downside is that you will have to digitize the ones you want to share with the team in Mural.
## Artefacts & Pre-Read Material
<!-- If there is material that will be useful for the participants to read before the Design Sprint add here, such as the sprint slide deck or design sprint material -->
### Handbook pages
<!-- Add a link to the category vision from the handbook -->
### Competitor resources
<!-- Add any solutions by competitors that are relevant to the Design Sprint topic and could be used as a source of inspiration. -->
### Articles on Design Sprints
* [The Design Sprint](https://www.gv.com/sprint/)
* [The Ultimate Guide To Remote Design Sprints](https://drive.google.com/file/d/16bwrAqHVf8qxovd87Q7LdzqwAgy7a6Rx/view?usp=sharing)
## Personas
Deciding which persona we are focusing on will be part of the Day 1 discussions in the workshop. The personas we are going to consider are:
<!-- Choose which personas could be target users, and choose from this list during the Sprint. Personas are described at https://handbook.gitlab.com/handbook/product/personas/
* [Parker (Product Manager)](https://handbook.gitlab.com/handbook/product/personas/#parker-product-manager)
* [Delaney (Development Team Lead)](https://handbook.gitlab.com/handbook/product/personas/#delaney-development-team-lead)
* [Presley (Product Designer)](https://handbook.gitlab.com/handbook/product/personas/#presley-product-designer)
* [Sasha (Software Developer)](https://handbook.gitlab.com/handbook/product/personas/#sasha-software-developer)
* [Priyanka (Platform Engineer)](https://handbook.gitlab.com/handbook/product/personas/#priyanka-platform-engineer)
* [Sidney (Systems Administrator)](https://handbook.gitlab.com/handbook/product/personas/#sidney-systems-administrator)
* [Rachel (Release Manager)](https://handbook.gitlab.com/handbook/product/personas/#rachel-release-manager)
* [Simone (Software Engineer in Test)](https://handbook.gitlab.com/handbook/product/personas/#simone-software-engineer-in-test)
* [Allison (Application Ops)](https://handbook.gitlab.com/handbook/product/personas/#allison-application-ops)
* [Ingrid (Infrastructure Operator)](https://handbook.gitlab.com/handbook/product/personas/#ingrid-infrastructure-operator)
* [Dakota (Application Development Director)](https://handbook.gitlab.com/handbook/product/personas/#dakota-application-development-director)
* [Dana (Data Analyst)](https://handbook.gitlab.com/handbook/product/personas/#dana-data-analyst)
* [Eddie (Content Editor)](https://handbook.gitlab.com/handbook/product/personas/#eddie-content-editor)
* [Amy (Application Security Engineer)](https://handbook.gitlab.com/handbook/product/personas/#amy-application-security-engineer)
* [Isaac (Infrastructure Engineer)](https://handbook.gitlab.com/handbook/product/personas/#isaac-infrastructure-security-engineer)
* [Alex (Security Operations Engineer)](https://handbook.gitlab.com/handbook/product/personas/#alex-security-operations-engineer)
* [Cameron (Compliance Manager)](https://handbook.gitlab.com/handbook/product/personas/#cameron-compliance-manager)
-->
## Pre-Sprint Preparation | Due Date: `Add Date`
- [ ] Promote this issue to an epic.
- [ ] Finalize objective and outputs.
- [ ] Finalize participant list.
- [ ] Create a dedicated Slack channel and add participants.
- [ ] Create issues for each day of the sprint.
- [ ] Prepare activity slide deck.
- [ ] Prepare Mural Board and ensure participant access.
- [ ] Prepare instructional videos for activities (Lightning Talks, HMWs, Crazy 8s etc).
- [ ] Organize and inform team members who will be providing lightning talk recordings.
- [ ] Open a recruitment issue for user testing.
- [ ] Create sync meetings in calendars for all participants.
- [ ] Record Kickoff Video.
- [ ] Do a Sprint test run.
## Sprint Kickoff | `Add Date`
#### Pre-Day Facilitator Checklist:
- [ ] Ensure [Kickoff Issue](Add Link) is complete.
- [ ] Assign participants to the [Kickoff Issue](Add Link).
- [ ] Ensure warm-up exercise Mural is set up.
- [ ] Prep Q&A issue thread.
- [ ] Send a `Welcome to the Sprint` slack message.
| Activity | Type of Activity | Duration | Tool | Description |
|---|---|---|---|---|
| Introduction to Design Sprints | Async | 20 Minutes | Video Recording | • The facilitator gives an overview of the Sprint, including details about what they are, why they are used, and why they can help solve the problem for this Sprint. <br/> • The facilitator gives participants an overview of what they need to complete a Design Sprint such as a run down of the rules, and supples, as well as an agenda and basic expectations. <br/> • The facilitator gives participants an overview of the problem we will be solving and allows for an async Q&A period. |
| Icebreaker | Async | 5 Minutes | Mural | • All Sprint participants give an async introduction in Mural. |
| Q&A Period | Async | 5 Minutes | GitLab and Slack | • Participants can ask questions about the Sprint. (Optional) |
| Record Lightning Talk | Async | 10 Minutes | Zoom | • Participants record their Lightning Talk. |
#### Post-Day Facilitator Checklist:
- [ ] Answer any questions that come up during the Q&A period.
- [ ] Send a homework reminder in the Slack channel.
## Day 1 - Sprint Homework | `Add Date`
#### Pre-Day Facilitator Checklist:
- [ ] Ensure [Day 1 Issue](Add Link) is complete.
- [ ] Ensure Lightning Talk recordings are added to the [Day 1 Issue](Add Link).
- [ ] Ensure participants have access to the Note Taking Activity Walkthrough Video.
- [ ] Ensure HMW section on Mural is organized.
- [ ] Ensure participants have access to the HMW Activity Walkthrough video.
| Activity | Type of Activity | Duration | Tool | Description |
|---|---|---|---|---|
| Watch Lightning Talks | Async | 15 Minutes Per Talk | Video Recording and Note Taking Tool | • Participants will watch lightning talks and complete the note-taking activity async. <br/> • The Facilitator will provide an overview video of what is expected during the note taking portion of this activity. |
| How Might Wes (HMWs) | Async | 20 Minutes | Mural | • Participants will take their notes from the Lightning Talk activity and craft some HMWs around the opportunities uncovered. <br/> • The facilitator will provide participants a video to describe the HMW activity and review what makes a good HMW statement. <br/> • The facilitator will also be available to sync on Slack for any questions around the activity. |
#### Post-Day Facilitator Checklist:
- [ ] Answer any questions that come up during the async HMW activity.
- [ ] Send a sync session reminder in the Slack channel.
## Day 1 - Sync Session | `Add Date`
#### Pre-Day Facilitator Checklist:
- [ ] Ensure all sync Mural boards are organized (Affinity Mapping, Goals, Hurdles, Squiggle Birds).
- [ ] Ensure sync session is recorded.
| Activity | Type of Activity | Duration | Tool | Description |
|---|---|---|---|---|
| Affinity Mapping | Sync | 30 Minutes | Zoom and Mural | • Participants take turns reading aloud their HMWs. (5 minutes). <br/> • Once the review has completed, the facilitator will choose an Affinity Mapper who will be in charge of categorizing the HMWs with the help of the entire group (10 Minutes). <br/> • Once the HMWs are organized into categories, the group will do a round of dot voting on the categories we want to focus on for the Sprint. Each participant will get three votes, and vote individually on the category they feel is most important to work on (10 Minutes). <br/> • The facilitator will allow time for discussion around the HMW groups chosen, and see if there needs to be adjustments (5 Minutes). |
| Sprint Goal | Sync | 20 Minutes | Zoom and Mural | • Based on the outcomes of the HMW activity, participants start by asking themselves the following question: “If everything worked out perfectly, what would that look like for this project?” <br/> • Each participant writes one Sprint goal on a Mural sticky starting with “By the end of the Sprint…” (10 Minutes) <br/> • Everyone on the team should share their Sprint Goal with the larger group and post them on the Mural (5 Minutes). <br/> • Everyone is given one dot to vote on what they think the Sprint Goal should be. (5 Minutes) |
| Sprint Hurdles | Sync | 20 Minutes | Zoom and Mural | • Participants will list out possible critical hurdles, in the form of a question, that may stop you from reaching your goal: What could stop us or heavily impact us from reaching our goals? <br/> • Each question must start with Can we... <br/> • Each person can only write 2 questions (10 Minutes) <br/> • Everyone on the team should share their Hurdles back to the larger group and post them up on the Mural (5 Minutes). <br/> • Everyone is given three to vote on what they think are the most important to focus on as challenges toward the Goal. (5 Minutes) |
| Recap of Day | Sync | 5 Minutes | Zoom and Mural | • Facilitator gives and overview of what has been completed so far during Day 1 of the Sprint and expectations for Day 2 Homework |
| Squiggle Birds | Sync | 5 Minutes | Zoom, Paper and Pen/Sharpie | • Sync warm-up drawing activity to prep for next async tasks. <br/> • The facilitator will draw a squiggle on Mural and encourage all participants to also make a squiggle. <br/> • Everyone will then turn the squiggle into a bird. <br/> • The facilitator will share that "Our minds are great at recognizing patterns." Sketches are only used to convey an idea, so they don't need to be super detailed or accurate. |
#### Post-Day Facilitator Checklist:
- [ ] Send a Day 1 overview and homework reminder in the Slack channel.
- [ ] Post-sync session recording in the Slack channel.
- [ ] Ensure [Day 2 Issue](Add Link) is complete.
- [ ] Ensure participants have access to the Crazy 8s Walkthrough Video.
- [ ] Ensure the Crazy 8s section on Mural is organized.
## Day 2 - Sprint Homework | (Add Date)
#### Pre-Day Facilitator Checklist:
- [ ] Ensure Ideation recordings are added to the [Day 2 Issue](Add Link).
- [ ] Ensure participants have access to the Ideation Walkthrough Videos.
- [ ] Ensure the Ideation section on Mural is organized.
| Activity | Type of Activity | Duration | Tool | Description |
|---|---|---|---|---|
| Note Recap | Async | Google Docs | 5 Minutes | • Review all the notes that were taken during Day 1. <br/> • Review all the HMW stickies to jog your memory. |
| Ideas List | Async | Google Docs | 5 Minutes | • On a piece of paper jot down any solutions that come to mind around solving HMW statements. |
| Crazy 8s | Async | Paper and Marker/Pen | 8 Minutes | • Grab your printer paper and create an 8-panel page by folding your paper in half 3 times. <br/> • Draw a sketch for an idea in each rectangle. <br/> • Start at the top of your HMW statements/ideas list from the previous activity.|
| Share-out Prep | Async | Mural | 10 Minutes | • In preparation for the share-out, take a photo of your Crazy 8 paper and add it to the Mural. |
#### Post-Day Facilitator Checklist:
- [ ] Send a sync session reminder in the Slack channel.
## Day 2 - Sync Session | `Add Date`
#### Pre-Day Facilitator Checklist:
- [ ] Ensure sync Murals are organized (Crazy 8s, Storyboarding).
- [ ] Ensure sync session is recorded.
| Activity | Type of Activity | Duration | Tool | Description |
|---|---|---|---|---|
| Crazy 8's Share out and Voting | Sync | 15 Minutes | Zoom and Mural | • Each person will have two minutes to present their ideas to the team. <br/> • After each team member has gotten the chance to present their ideas, we will do a round of dot voting. <br/> • Vote on the ideas you think will be best to solve our Sprint problem. <br/> • Each team member will get 3 votes. |
| Storyboarding Key Moments | Sync - 2 Groups | 30 Minutes | Zoom, Paper and Sharpie/Pen | • Take the first 10 minutes to write down the 8-10 key moments individually. <br/> • As a team decide on the ideal storyboard together. <br/> • Try and bring out the task that needs to be done and the emotion that you would like the user to experience. <br/> • No drawing yet! |
| Storyboard Details | Sync | 20 Minutes | Zoom, Paper and Pen/Sharpie | • Take your draft storyboard and give it more detail. <br/> • DRAW BIG! Sketch 1 key moment per 8.5x11 page. <br/> • Each person on the team should sketch at least 1 key moment. <br/> • Focus on actions and emotions. |
| Put Together the Story | Sync | 10 Minutes | Zoom and Mural | • Each person will take a photo of their storyboard and add it to the Mural. |
| Storyboard Share Out and Voting | Sync | 15 Minutes | Zoom and Mural | • Each group takes turns presenting their story to the Sprint team. <br/> • Once both teams have had the chance to present their storyboard, well hold a round of voting. <br/> • Each person will be given 3 votes to vote for any part of each experience they like. <br/> • The Decider gets 6 votes for this activity, 3 mega-likes and 3 dislikes. |
| All in One or Rumble | Sync | 5 Minutes | Zoom | • Decide as a group if you want to incorporate the best parts of both storyboards into one or if you want to test both storyboards against each other during the testing phase. |
#### Post-Day Facilitator Checklist:
- [ ] Send a Day 2 overview and homework reminder in the Slack channel.
- [ ] Post-sync session recording in the Slack channel.
- [ ] Ensure [Day 3 Issue](Add Link) is complete.
## Day 3 - Group Sprint Homework | (Add Date)
#### Post-Day Facilitator Checklist:
- [ ] Set up a Figma File for the prototype and ensure it's shared with the group.
| Activity | Type of Activity | Duration | Tool | Description |
|---|---|---|---|---|
| Prototyping | Async | 1 Hour | Figma | • The Designer will craft out a prototype based on the storyboard for the team to review. |
| Prototyping Feedback | Async | 10 Minutes | Figma | • Once the Designer has completed the prototype, the team will review it and leave feedback. <br/> • There will only be a single round of feedback before hallway testing (where we will receive additional feedback from users). |
| Review Hallway Testing Slides | Async | 10 Minutes | Slides | • Review the details on what Hallway Testing is to prepare for the next sync session. |
#### Post-Day Facilitator Checklist:
- [ ] Send a sync session reminder in the Slack channel.
## Day 3 - Sync Session | (Add Date)
#### Pre-Day Facilitator Checklist:
- [ ] Ensure sync Murals are organized (Hallway Testing Prep).
- [ ] Ensure sync session is recorded.
- [ ] Ensure the prototype is done and has been adjusted from the feedback.
- [ ] Gathered a few potential Hallway Test Volunteers.
| Activity | Type of Activity | Duration | Tool | Description |
|---|---|---|---|---|
| Define a Research Objective | Sync | 10 Minutes | Zoom and Mural | • As a group, write a research objective for your hallway test. Make sure to capture: What you want to learn, Who you want to talk to, What you plan to do with what you learn. |
| Write a Test Scenario | Sync | 10 Minutes | Zoom and Mural | • As a group, write a test scenario for your hallway test. <br/> • Write down a list of key tasks that youd like the participant to complete while using the prototype. |
| Write Test Questions | Sync | 10 Minutes | Zoom and Mural | • As a group, write a test scenario for your hallway test. <br/> • Craft a list of questions and / or tasks that youll ask participants to answer or complete in order to answer your research objectives. |
| Hallway Testing | Sync | 50 Minutes | Zoom | • Working in groups of 2-3, review the discussion guide and prototype. <br/> • Determine who will ask questions and who will take notes. Remember to switch roles after each test! <br/> • Its up to you where you take notes. <br/> • Join the Zoom meeting with your assigned person & test your prototype. <br/> • Have the team document what they hear and be prepared to share back with the larger sprint team. |
| Hallway Testing Share-out | Sync | 20 Minutes | Zoom | • Each group will have roughly 5 minutes to present their findings from Hallway Testing. Each team should present: <br/> • What were the common themes? <br/> • What did you hear that was surprising? <br/> • Any red flags? <br/> • Thank participants for their time. |
#### Post-Day Facilitator Checklist:
- [ ] Summarize themes of Hallway Testing and share with the Slack channel and the [Day 3 Issue](Add Link).
- [ ] Optionally, share with UX, Product, and other relevant Slack channels.
- [ ] Share with team next steps related to Day 4 and Usertesting.
## Day 4 - Usertesting | (Add Date)
<!-- Day 4 can happen at a later date when it makes the most sense. Use the problem validation issue template for Day 4. -->
Day 4 consists of a round of user testing which typically happens a week or more after the first three days complete.
* **Day Four Issue:** (Day 4 Issue Link)
## Ground Rules
* Honor the Facilitator's directions. They're the guide for the entire process.
* Minimise distractions: During the week you will need to dedicate some hours to the Sprint for async tasks and sync video conferences. During this time we recommend blocking time in your calendar and having devices or apps with notifications turned off during that time.
* All opinions are valid and are equally important, however, the Decider has the ultimate, final decision.
* Everyone is an active participant in a sync activity (with the exception of the Observers).
* One conversation at a time.
* Document as much as you can: We should have concrete outputs to share with broader team. Also interesting ideas or fixes should be documented to be transferred in issues for our backlog.
* Stick to scheduled breaks during sync calls. The Facilitator will guide each session and set break times.
* The Sprint is one of the few chances we get to work so closely together. Have fun!

View File

@ -0,0 +1,44 @@
<!--
* Use this issue template for suggesting new docs or updates to existing docs.
Note: Doc work as part of feature development is covered in the Feature Request template.
-->
- [ ] Start this issue's title with `Docs:` or `Docs feedback:`.
## Problem to solve
<!--
Include the following detail as necessary:
* What feature(s) are affected?
* What docs or doc section affected? Include links or paths.
* Is there a problem with a specific document, or a feature/process that's not addressed sufficiently in docs?
* Any other ideas or requests?
-->
## Further details
<!--
* Any concepts, procedures, reference info we could add to make it easier to successfully use this?
* Include use cases, benefits, and/or goals for this work.
* If adding content: What audience is it intended for? (What roles and scenarios?)
-->
## Proposal
<!-- Further specifics for how can we solve the problem. -->
## Who can address the issue
<!-- What if any special expertise is required to resolve this issue? -->
## Other links/references
<!-- For example, related GitLab issues/MRs -->
/label ~"documentation" /label ~"docs-only"
/label ~"type::maintenance" ~"maintenance::refactor"
/milestone %Backlog

View File

@ -0,0 +1,41 @@
## Experiment summary
We believe that... {describe your hypothesis in one sentence}
To verify that, we will... {describe your test in one sentence}
And well measure the impact on... {metrics}
## Hypothesis
<!-- The hypothesis represents the high-level thought process in creating the experiment but does not need to be proven in one experiment. For example, you could have a hypothesis that “users would benefit from more easily being able to have a one-click-sandbox” and your first experiment could fail, that doesnt void your hypothesis only indicates you may need to think of a new iterative experiment that would still align with your hypothesis. -->
## Supporting data
<!-- Why should we run this experiment? Why do you belive your Hypothesis to be true? -->
## Expected outcome
<!-- What is the expected outcome of this experiment, what metric are we trying to move? Are there any metrics we know we do not want to impact? -->
## Experiment design & implementation
<!-- What is the experiment were going to run? -->
## Known assumptions
<!-- This is an area to call out known assumptions in the experiment, this is especially helpful for any future colleagues that join the team so they understand other potential influences and how they were accounted for. This section is also helpful in framing possible scenarios and to keep the door open for the next steps. For example, were hoping our experiment will ... but were assuming .... This is a known assumption and depending on the results of the experiment could impact the direction we take on any future iterations. -->
## Results, lessons learned, next steps
<!-- What were the results of the experiment? Was the experiment a success or a failure? Based on the results should we remove the code or advocate that it become a permanent part? Are there future experiments to run based off these results (include a link to new issue)? For example, our trial experiment was successful we ... but saw .... Our next experiment (link) will focus on .... -->
## Checklist
- [ ] Fill in the experiment summary and write more about the details of the
experiment in the rest of the issue description. Some of these may be
filled in through time (the "Result, learnings, next steps" section for
example) but at least the experiment summary should be filled in right
from the start.
/label ~"workflow::validation backlog" ~"experiment idea"

View File

@ -0,0 +1,25 @@
<!-- Title suggestion: Experiment Implementation: [description] -->
# Experiment Summary
<!-- Quick rundown of what is being done or a link to the Experiment epic -->
# Design
<!-- This should include the contexts that determine the reproducibility of an experiment. -->
# Control vs Candidate Experience
<!-- This should include a screenshot of the ground-truth vs experiment and any helpful context regarding expected outcomes -->
| Control | Experiment |
| ------- | ---------- |
| | |
# Tracking Details
<!-- Record of what was tried/done when -->
| activity | category | action | label |
| -------- | -------- | ------ | ----- |
| | | | |

View File

@ -0,0 +1,10 @@
<!-- This template is a great use for issues that are feature::additions or technical tasks for larger issues.-->
### Proposal
<!-- Use this section to explain the feature and how it will work. It can be helpful to add technical details, design proposals, and links to related epics or issues. -->
<!-- Consider adding related issues and epics to this issue. You can also reference the detailed Feature Proposal Template for additional details to consider adding to this issue.
-->
/label ~Category: /label ~"type::feature" ~"feature::addition" ~documentation

View File

@ -0,0 +1,17 @@
<!-- This issue template can be used as a great starting point for feature requests.
The goal of this template is brevity for quick/smaller iterations. For a more thorough list of considerations for larger features or feature sets, you can leverage the detailed feature proposal. -->
### Release notes
<!-- What is the problem and solution you're proposing? This content sets the overall vision for the feature and serves as the release notes that will populate in various places. -->
### Problem to solve
<!-- What is the user problem you are trying to solve with this issue? -->
### Proposal
<!-- Use this section to explain the feature and how it will work. It can be helpful to add technical details, design proposals, and links to related epics or issues. -->
/label ~"type::feature"

View File

@ -0,0 +1,44 @@
<!-- This issue template can be used as a great starting point for feature requests. The first section "Release notes" is required if you want to have your release post blog MR auto generated. Currently in BETA, details on the **release post item generator** can be found in the handbook: https://about.gitlab.com/handbook/marketing/blog/release-posts/#release-post-item-generator and this video: https://www.youtube.com/watch?v=rfn9ebgTwKg. The next four sections: "Problem to solve", "Intended users", "User experience goal", and "Proposal", are strongly recommended in your first draft, while the rest of the sections can be filled out during the problem validation or breakdown phase. However, keep in mind that providing complete and relevant information early helps validate the problem and start working on a solution. -->
### Release notes
<!-- What is the problem and solution you're proposing? This content sets the overall vision for the feature and serves as the release notes that will populate in various places. -->
### Problem to solve
<!-- What problem do we solve? Try to define the who/what/why of the opportunity as a user story. For example, "As a (who), I want (what), so I can (why/value)." -->
### User experience goal
<!-- What is the single user experience workflow this problem addresses?
For example, "The user should be able to <perform a specific task>"
-->
### Proposal
<!-- How are we going to solve the problem? Try to include the user journey! -->
### Further details
<!-- Include use cases, benefits, goals, or any other details that will help us understand the problem better. -->
### Documentation
<!-- To be filled out later with links to Documentation Issues -->
### Impact
<!-- This section needs to be retained and filled in during the workflow planning phase of this feature proposal, if not earlier.
What risks does this change pose to this project? What additional test coverage or changes to tests will be needed? Will it require extensive testing?
Please list the test areas (unit, integration and end-to-end) that needs to be added or updated to ensure that this feature will work as intended. Please use the list below as guidance.
* Unit test changes
* Integration test changes
* End-to-end test change
-->
### Links / references
/label ~"type::feature"

View File

@ -0,0 +1,37 @@
<!--
Implementation issues are used break-up a large piece of work into small, discrete tasks that can
move independently through the build workflow steps. They're typically used to populate a Feature
Epic. Once created, an implementation issue is usually refined in order to populate and review the
implementation plan and weight.
-->
## Relevant links
<!--
Information that the developer might need to refer to when implementing the issue.
Basically a list of issues (bugs that are fixed, features implemented, etc. pp.)
-->
## Non-functional requirements
<!--
Add details for required items and delete others.
-->
- [ ] Documentation:
## Verification steps
<!--
Add verification steps to help team members test the implementation. This is particularly useful
during the ~"workflow::verification" step. You may not know exactly what the
verification steps should be during issue refinement, so you can always come back later to add
them.
1. Check-out the corresponding branch
1. ...
1. Profit!
-->
/label ~"workflow::refinement" /milestone %Backlog

View File

@ -0,0 +1,25 @@
## Summary
<!--
Please briefly describe what part of the code base needs to be refactored.
-->
## Improvements
<!--
Explain the benefits of refactoring this code.
-->
## Risks
<!--
Please list features that can break because of this refactoring and how you intend to solve that.
-->
## Involved components
<!--
List files or directories that will be changed by the refactoring.
-->
/label ~"type::maintenance"

View File

@ -0,0 +1,70 @@
<!--
🔧 GitLab Review-Template
Entferne oder passe Abschnitte an nach Bedarf
Markiere den Review-Typ und setze Häkchen bei erledigten Punkten
-->
## 🎯 Review-Übersicht
- **Reviewer:** @
- **Datum:** YYYY-MM-DD
- **Review-Typ:**
- [ ] Code
- [ ] Dokumentation
- [ ] Allgemeines Feedback
- **Ziel / Scope:** Kurze Beschreibung des geprüften Inhalts
---
## 📚 Kontext
> Fasse zusammen, worum es geht, verlinke Ticket, Issue, Spezifikation,
> Live-Demo …
---
## ✅ Was gut ist
- [ ] Erfüllt die Anforderungen
- [ ] Sauber strukturierter Code / klare Dokumentation
- [ ] Verständliche Kommentare / Beispiele
- **Stärken:**
- Punkt 1
- Punkt 2
---
## 🛠 Gefundene Probleme & Risiken
- [ ] Fehler in Logik / Typos
- [ ] Fehlende Tests / unklare Schnittstellen
- [ ] Inkonsistente Benennung / Formatierung
- **Details:**
1. Problem A Ort, Fehlermeldung, Reproduktion
2. Problem B Ort, Auswirkung
---
## 💡 Vorschläge & Empfehlungen
- Kurze, konkrete Verbesserungsideen:
- ☑️ Refactor: …
- ☑️ Ergänze Tests für …
- ☑️ Dokumentiere / Beispiel hinzufügen für …
- Alternative Ansätze:
---
## 🔍 Offene Fragen
1. Ist der Use-Case X abgedeckt?
2. War die Performance unter Last geprüft?
3. Weitere Unklarheiten: …
---
## 🚀 Nächste Schritte
- [ ] Autor nimmt Änderungen vor
- [ ] Zweitrunde Review geplant für YYYY-MM-DD
- [ ] Tests / CI-Pipeline erfolgreich

View File

@ -1,7 +1,30 @@
# Good™ Documentation
Dieses Repository enthält eine Beispielstruktur, nach welchen Regeln und in
welcher Ausführlichkeit sinnvoll dokumentiert werden sollte.
---
title: Good™ Documentation
description: |
Dieses Repository enthält eine Beispielstruktur, nach welchen Regeln und in welcher Ausführlichkeit sinnvoll dokumentiert werden sollte.
lang: de
date: 2025-06-03
authors:
- name: Nicole Dresselhaus
affiliation:
- name: Humboldt-Universität zu Berlin
url: https://hu-berlin.de
email: nicole.dresselhaus@hu-berlin.de
correspondence: true
orcid: 0009-0008-8850-3679
roles:
- Conceptualization
- "Writing first draft"
- "Writing review & editing"
- name: Till Grallert
affiliation:
- name: Humboldt-Universität zu Berlin
url: https://hu-berlin.de
email: till.grallert@hu-berlin.de
roles:
- Supervision
- Validation
---
## Ziel / Zweck
@ -12,29 +35,46 @@ Dinge für etwaige Nachfolger\*innen nicht vergisst.
## Nutzung
Das Unterverzeichnis `example-project` enthält folgende Struktur:
Wir haben GitLab-Templates, die man benutzen kann, wenn man ein Projekt startet.
Falls bereits Code oder ein Repository besteht, ist es am Besten, wenn man
dennoch im GitLab ein neues Projekt mit diesem Template erstellt und
anschließend die existierenden Dateien herüberkopiert.
```plain
example-project/
├── README.md
├── INSTALL.md (optional, bei aufwendiger Installation)
├── USAGE.md (optional, bei komplexeren Beispielen oder Workflows)
├── CONTRIBUTING.md (optional, falls Mitarbeit möglich)
├── CITATION.md (oder CITATION.cff)
├── LICENSE
├── CHANGELOG.md (optional)
├── examples/ (optional, Beispielskripte oder Notebooks)
│ └── example_workflow.ipynb
├── data/ (optional, kleine Beispieldaten)
│ └── sample_data.csv
└── src/
├── script.py
└── module/
└── helper.py
```
1. Neues Projekt erstellen
![](imgs/use_template_1.png)
2. Aus Template
![](imgs/use_template_2.png)
3. Gruppe wählen
![](imgs/use_template_3.png)
4. Template auswählen & erstellen
![](imgs/use_template_4.png)
Die jeweiligen benötigten Dateien können einfach kopiert werden und enthalten
jeweils eine Anleitung über ihren Inhalt
### Code-Project
Das
[Code-Project-Template](https://scm.cms.hu-berlin.de/methodenlabor/templates/code-project-template)
ist für Repositories gedacht, die irgendeine Art von Verarbeitung haben, bei der
primär Daten analysiert, weiterverarbeitet oder ausgewertet werden ODER es sich
um ein Applikationsprojekt im klassischen Sinne handelt.
Ziel ist hier die Entwicklung und langfristig die Installation,
Veröffentlichung,Nutzung und Wartung der Software.
Zur genauer Struktur und Handhabung sei auf die `README.md` dort verwiesen.
### Daten-Project
Analog zum Code-Project ist das
[Daten-Project-Template](https://scm.cms.hu-berlin.de/methodenlabor/templates/data-project-template)
für Repositories gedacht, die irgendeine Art von Daten als Output haben. Hierbei
geht es um die reine Vorverarbeitung der Daten und nicht um Analyse.
Typischerweise liegen hier z.b. Roh-Daten (Bilder, etc.) vor und der Output ist
ein Maschinenlesbares Format (z.b. JSON des Textes mit Annotationen).
Ziel ist hier die Dokumentation und die Reproduzierbarkeit von
`Quelle -> Datensatz`.
Zur genauer Struktur und Handhabung sei auf die `README.md` dort verwiesen.
## Wissenschaftlicher Hintergrund
@ -46,7 +86,7 @@ dokumentieren. Insbesondere hervorzuheben sind hier die
[Ten simple rules for documenting scientific software](https://doi.org/10.1371/journal.pcbi.1006561).
Für eine Ausführliche auseinandersetzung mit dieser Thematik siehe
`BACKGROUND.md`
[BACKGROUND.md](background/BACKGROUND.md)
## Bekannte Einschränkungen

File diff suppressed because one or more lines are too long

File diff suppressed because it is too large Load Diff

View File

@ -1,69 +1,322 @@
@article{wilson2017good,
title={Good enough practices in scientific computing},
author={Wilson, Greg and Bryan, Jennifer and Cranston, Karen and Kitzes, Justin and Nederbragt, Lex and Teal, Tracy K},
journal={PLoS computational biology},
volume={13},
number={6},
pages={e1005510},
year={2017},
publisher={Public Library of Science}
@book{AhnertEtAl2023CollaborativeHistoricalResearch,
title = {Collaborative {{Historical Research}} in the {{Age}} of {{Big Data}}: {{Lessons}} from an {{Interdisciplinary Project}}},
shorttitle = {Collaborative {{Historical Research}} in the {{Age}} of {{Big Data}}},
author = {Ahnert, Ruth and Griffin, Emma and Ridge, Mia and Tolfo, Giorgia},
date = {2023},
series = {Cambridge {{Elements}}: {{Historical Theory}} and {{Practice}}},
publisher = {Cambridge University Press},
location = {Cambridge},
doi = {10.1017/9781009175548},
url = {https://www.cambridge.org/core/elements/collaborative-historical-research-in-the-age-of-big-data/839C422CCAA6C1699DE8D353B3A1960D},
urldate = {2023-01-26},
abstract = {This book is output of the Living with Machines project},
langid = {english},
language = {en},
keywords = {field: History,project: documentation,Project: Methods Lab 🥼},
file = {/home/drezil/Zotero/storage/ET5S8DMH/Ahnert et al. - 2023 - Collaborative Historical Research in the Age of Big Data Lessons from an Interdisciplinary Project.pdf}
}
% == BibLateX quality report for AhnertEtAl2023CollaborativeHistoricalResearch:
% ? Title looks like it was stored in title-case in Zotero
@article{prlic2012ten,
title={Ten simple rules for documenting scientific software},
author={Prli{\'c}, Andreas and Procter, James B},
journal={PLoS Computational Biology},
volume={8},
number={12},
pages={e1002802},
year={2012},
publisher={Public Library of Science}
@report{AltenhonerEtAl2023DFGPraxisregeln,
title = {DFG-Praxisregeln "Digitalisierung". Aktualisierte Fassung 2022.},
author = {Altenhöner, Reinhard and Berger, Andreas and Bracht, Christian and Klimpel, Paul and Meyer, Sebastian and Neuburger, Andreas and Stäcker, Thomas and Stein, Regine},
date = {2023-02-16},
url = {https://zenodo.org/record/7435724},
urldate = {2023-03-07},
abstract = {Die DFG-Praxisregeln „Digitalisierung“ stellen eine zentrale Grundlage für DFG-geförderte Projekte im Programm „Digitalisierung und Erschließung“ dar: Sie formulieren Standards und enthalten Informationen zu organisatorischen, methodischen und technischen Fragen im Kontext der Digitalisierung und Erschließung forschungsrelevanter Objekte. Sie leisten damit einen wichtigen Beitrag zur Nachhaltigkeit, Zugänglichkeit und Anschlussfähigkeit geförderter Projekte und der in diesem Zusammenhang entstehenden Infrastruktur. Das vorliegende Dokument stellt eine aktualisierte Fassung der zuletzt 2016 durch die DFG publizierten Praxisregeln dar. Es wurde in Absprache mit der DFG-Geschäftsstelle durch eine vom NFDI-Konsortium NFDI4Culture initiierte Autor*innengruppe erarbeitet, deren Mitglieder mehrheitlich seit langem an der Ausgestaltung der Praxisregeln beteiligt waren sowie aktiv in die NFDI-Konsortien NFDI4Culture, NFDI4Memory, NFDI4Objects und Text+ eingebunden sind. Die jetzt überarbeitet vorliegenden Praxisregeln „Digitalisierung“ dienen als Ausgangspunkt für eine material- und communitybezogene Ausdifferenzierung der Praxisregeln durch die Communitys. Alle mit der Digitalisierung forschungsrelevanter Objekte befassten Communitys und Einrichtungen sind dazu aufgerufen, mit ihrer Expertise am weiteren Prozess mitzuwirken.},
langid = {deu},
language = {deu},
keywords = {Digital Scholarly Editions,Digitalisierung,Erschließung,Informationsinfrastrukturen,NFDI,Praxisregeln,project: documentation,Project: Methods Lab 🥼,Standardbildung,TEI: Text Encoding Initiative},
file = {/home/drezil/Zotero/storage/46FYRPPH/Altenhöner et al. - 2023 - DFG-Praxisregeln Digitalisierung. Aktualisierte Fassung 2022..pdf}
}
% == BibLateX quality report for AltenhonerEtAl2023DFGPraxisregeln:
% Missing required field 'type'
% Missing required field 'institution'
% ? Title looks like it was stored in title-case in Zotero
% ? unused Library catalog ("Zenodo")
@article{smith2016software,
title={Software citation principles},
author={Smith, Arfon M and Katz, Daniel S and Niemeyer, Kyle E and FORCE11 Software Citation Working Group and others},
journal={PeerJ Computer Science},
volume={2},
pages={e86},
year={2016},
publisher={PeerJ Inc.}
@article{BarkerEtAl2022IntroducingFAIR,
title = {Introducing the {{FAIR Principles}} for Research Software},
author = {Barker, Michelle and Chue Hong, Neil P. and Katz, Daniel S. and Lamprecht, Anna-Lena and Martinez-Ortiz, Carlos and Psomopoulos, Fotis and Harrow, Jennifer and Castro, Leyla Jael and Gruenpeter, Morane and Martinez, Paula Andrea and Honeyman, Tom},
date = {2022-10-14},
journaltitle = {Scientific Data},
shortjournal = {Sci Data},
volume = {9},
number = {1},
pages = {622},
publisher = {Nature Publishing Group},
issn = {2052-4463},
doi = {10.1038/s41597-022-01710-x},
url = {https://www.nature.com/articles/s41597-022-01710-x},
urldate = {2024-09-10},
abstract = {Research software is a fundamental and vital part of research, yet significant challenges to discoverability, productivity, quality, reproducibility, and sustainability exist. Improving the practice of scholarship is a common goal of the open science, open source, and FAIR (Findable, Accessible, Interoperable and Reusable) communities and research software is now being understood as a type of digital object to which FAIR should be applied. This emergence reflects a maturation of the research community to better understand the crucial role of FAIR research software in maximising research value. The FAIR for Research Software (FAIR4RS) Working Group has adapted the FAIR Guiding Principles to create the FAIR Principles for Research Software (FAIR4RS Principles). The contents and context of the FAIR4RS Principles are summarised here to provide the basis for discussion of their adoption. Examples of implementation by organisations are provided to share information on how to maximise the value of research outputs, and to encourage others to amplify the importance and impact of this work.},
langid = {english},
language = {en},
keywords = {Policy,project: documentation,Project: Methods Lab 🥼,Research management,RSE: Research Software Engineering},
file = {/home/drezil/Zotero/storage/VRFPNWKW/VRFPNWKW_Barker et al. - 2022 - Introducing the FAIR Principles for research software.pdf}
}
% == BibLateX quality report for BarkerEtAl2022IntroducingFAIR:
% Unexpected field 'publisher'
% ? unused Library catalog ("www.nature.com")
@article{maria2019jupyter,
title={Jupyter notebooks—a publishing format for reproducible computational workflows},
author={Kluyver, Thomas and Ragan-Kelley, Benjamin and P{\'e}rez, Fernando and Granger, Brian and Bussonnier, Matthias and Frederic, Jonathan and Kelley, Kyle and Hamrick, Jessica B and Grout, Jason and Corlay, Sylvain and others},
journal={Positioning and Power in Academic Publishing: Players, Agents and Agendas},
volume={20},
pages={87--90},
year={2016},
publisher={IOS Press}
@book{CremerEtAl2024Projektmanagement,
title = {Projektmanagement und Digital Humanities: Zur klugen Gestaltung der Zusammenarbeit},
editor = {Cremer, Fabian and Dogunke, Swantje and Neubert, Anna Maria and Wübbena, Thorsten},
date = {2024-04},
publisher = {Bielefeld University Press},
location = {Bielefeld},
doi = {10.14361/9783839469675},
abstract = {Die Professionalisierung des Projektmanagements in den Digital Humanities: Theorie und Praxis zum Weiterdenken.},
langid = {ngerman},
language = {de},
keywords = {field: Digital Humanities (DH),Project management,project: documentation,Project: Methods Lab 🥼},
file = {/home/drezil/Zotero/storage/GYJK3NUY/Cremer et al. - 2024 - Projektmanagement und Digital Humanities Zur klugen Gestaltung der Zusammenarbeit.pdf;/home/drezil/Zotero/storage/XQ6AI49P/Cremer et al. - 2024 - Projektmanagement und Digital Humanities Zur klugen Gestaltung der Zusammenarbeit.pdf}
}
% == BibLateX quality report for CremerEtAl2024Projektmanagement:
% Missing required field 'author'
@misc{endings2020principles,
title = {Endings Principles for Digital Longevity},
author = {{Endings Project}},
year = {2020},
url = {https://endings.uvic.ca/principles.html}
@article{Diehl2025JournalOpenSource,
title = {The {{Journal}} of {{Open Source Software}} ({{JOSS}}): {{Bringing Open-Source Software Practices}} to the {{Scholarly Publishing Community}} for {{Authors}}, {{Reviewers}}, {{Editors}}, and {{Publishers}}},
shorttitle = {The {{Journal}} of {{Open Source Software}} ({{JOSS}})},
author = {Diehl, Patrick and Soneson, Charlotte and Kurchin, Rachel C. and Mounce, Ross and Katz, Daniel S.},
date = {2025-02-04},
journaltitle = {Journal of Librarianship and Scholarly Communication},
volume = {12},
number = {2},
publisher = {Iowa State University Digital Press},
issn = {2162-3309},
doi = {10.31274/jlsc.18285},
url = {https://www.iastatedigitalpress.com/jlsc/article/id/18285/},
urldate = {2025-05-15},
abstract = {Introduction: Open-source software (OSS) is a critical component of open science, but contributions to the OSS ecosystem are systematically undervalued in the current academic system. The Journal of Open Source Software (JOSS) contributes to addressing this by providing a venue (that is itself free, diamond open access, and all open-source, built in a layered structure using widely available elements/services of the scholarly publishing ecosystem) for publishing OSS, run in the style of OSS itself. A particularly distinctive element of JOSS is that it uses open peer review in a collaborative, iterative format, unlike most publishers. Additionally, all the components of the process—from the reviews to the papers to the software that is the subject of the papers to the software that the journal runs—are open. Background: We describe JOSSs history and its peer review process using an editorial bot, and we present statistics gathered from JOSSs public review history on GitHub showing an increasing number of peer reviewed papers each year. We discuss the new JOSSCast and use it as a data source to understand reasons why interviewed authors decided to publish in JOSS. Discussion and Outlook: JOSSs process differs significantly from traditional journals, which has impeded JOSSs inclusion in indexing services such as Web of Science. In turn, this discourages researchers within certain academic systems, such as Italys, which emphasize the importance of Web of Science and/or Scopus indexing for grant applications and promotions. JOSS is a fully diamond open-access journal with a cost of around US\$5 per paper for the 401 papers published in 2023. The scalability of running JOSS with volunteers and financing JOSS with grants and donations is discussed.},
issue = {2},
langid = {english},
language = {eng},
keywords = {project: documentation,Project: Methods Lab 🥼},
file = {/home/drezil/Zotero/storage/G4T6JNUU/Diehl et al. - 2025 - The Journal of Open Source Software (JOSS) Bringing Open-Source Software Practices to the Scholarly.pdf}
}
% == BibLateX quality report for Diehl2025JournalOpenSource:
% Unexpected field 'publisher'
% ? Title looks like it was stored in title-case in Zotero
% ? unused Library catalog ("www.iastatedigitalpress.com")
@article{katz2021open,
title={The Journal of Open Source Software (JOSS)},
author={Katz, Daniel S and Niemeyer, Kyle E and Smith, Arfon M},
journal={PeerJ Computer Science},
volume={7},
pages={e432},
year={2021},
publisher={PeerJ Inc.}
@misc{EndingsPrinciples221,
title = {Endings {{Principles}} for {{Digital Longevity}}},
shorttitle = {Endings {{Principles}}},
author = {{Endings Project Team}},
date = {2023-03-03},
url = {https://endings.uvic.ca/principles.html},
urldate = {2024-05-14},
abstract = {Enabling Sustainable Digital Humanities Projects},
langid = {english},
language = {en},
version = {2.2.1},
keywords = {project: documentation,Project: Methods Lab 🥼,Project: Tool Registry 🧰,talk: 2024 Bochum,writing: 2024 Tool Registry}
}
% == BibLateX quality report for EndingsPrinciples221:
% ? Title looks like it was stored in title-case in Zotero
@article{lamprecht2020towards,
title={Towards FAIR principles for research software},
author={Lamprecht, Anna-Lena and Garcia, Leyla and Kuzak, Mateusz and Martinez, Carlos and Arcila, Ricardo and Martin Del Pico, Eva and others},
journal={Data Science},
volume={3},
number={1},
pages={37--59},
year={2020},
publisher={IOS Press}
@standard{Forschungsgemeinschaft2025LeitlinienzurSicherung,
title = {Leitlinien zur Sicherung guter wissenschaftlicher Praxis},
date = {2024-09},
publisher = {Deutsche Forschungsgemeinschaft},
doi = {10.5281/zenodo.14281892},
url = {https://zenodo.org/records/14281892},
urldate = {2025-05-15},
abstract = {The DFG´s Code of Conduct “Safeguarding Good Research Practice” represents the consensus among the member organisations of the DFG on the fundamental principles and standards of good practice and are upheld by these organisations. These guidelines underline the importance of integrity in the everyday practice of research and provide researchers with a reliable reference with which to embed good research practice as an established and binding aspect of their work.},
langid = {ngerman},
language = {de},
version = {1.2},
keywords = {code of conduct,Deutsche Forschungsgemeinschaft,DFG,German research foundation,good scientific practice,gute wissenschaftliche Praxis,Kodex,Leitlinien zur Sicherung guter wissenschaftlicher Praxis,project: documentation,Project: Methods Lab 🥼,research integrity,scientific misconduct,Wissenschaftliche Integrität,wissenschaftliches Fehlverhalten},
file = {/home/drezil/Zotero/storage/DMF478TJ/2024 - Leitlinien zur Sicherung guter wissenschaftlicher Praxis.pdf}
}
% == BibLateX quality report for Forschungsgemeinschaft2025LeitlinienzurSicherung:
% Unexpected field 'title'
% Unexpected field 'publisher'
% Unexpected field 'language'
% Unexpected field 'version'
% ? unused Committee ("Team „Wissenschaftliche Integrität“")
% ? unused Library catalog ("Zenodo")
@article{Hasselbring2020OpenSourceResearch,
title = {Open {{Source Research Software}}},
author = {Hasselbring, Wilhelm and Carr, Leslie and Hettrick, Simon and Packer, Heather and Tiropanis, Thanassis},
date = {2020-08},
journaltitle = {Computer},
shortjournal = {Computer},
volume = {53},
number = {8},
pages = {84--88},
issn = {0018-9162, 1558-0814},
doi = {10.1109/MC.2020.2998235},
url = {https://ieeexplore.ieee.org/document/9153295/},
urldate = {2025-06-05},
keywords = {Praxisregeln,project: documentation,Project: Methods Lab 🥼,Research Software Engineering,Standardbildung},
file = {/home/drezil/Zotero/storage/E8CWCEFF/Hasselbring et al. - 2020 - Open Source Research Software.pdf}
}
% == BibLateX quality report for Hasselbring2020OpenSourceResearch:
% 'issn': not a valid ISSN
% ? Title looks like it was stored in title-case in Zotero
% ? unused Library catalog ("DOI.org (Crossref)")
@article{JimenezEtAl2017FourSimpleRecommendations,
title = {Four Simple Recommendations to Encourage Best Practices in Research Software},
author = {Jiménez, Rafael C. and Kuzak, Mateusz and Alhamdoosh, Monther and Barker, Michelle and Batut, Bérénice and Borg, Mikael and Capella-Gutierrez, Salvador and Chue Hong, Neil and Cook, Martin and Corpas, Manuel and Flannery, Madison and Garcia, Leyla and Gelpí, Josep Ll. and Gladman, Simon and Goble, Carole and González Ferreiro, Montserrat and Gonzalez-Beltran, Alejandra and Griffin, Philippa C. and Grüning, Björn and Hagberg, Jonas and Holub, Petr and Hooft, Rob and Ison, Jon and Katz, Daniel S. and Leskošek, Brane and López Gómez, Federico and Oliveira, Luis J. and Mellor, David and Mosbergen, Rowland and Mulder, Nicola and Perez-Riverol, Yasset and Pergl, Robert and Pichler, Horst and Pope, Bernard and Sanz, Ferran and Schneider, Maria V. and Stodden, Victoria and Suchecki, Radosław and Svobodová Vařeková, Radka and Talvik, Harry-Anton and Todorov, Ilian and Treloar, Andrew and Tyagi, Sonika and Van Gompel, Maarten and Vaughan, Daniel and Via, Allegra and Wang, Xiaochuan and Watson-Haigh, Nathan S. and Crouch, Steve},
date = {2017-06-13},
journaltitle = {F1000Research},
shortjournal = {F1000Res},
volume = {6},
pages = {876},
issn = {2046-1402},
doi = {10.12688/f1000research.11407.1},
url = {https://f1000research.com/articles/6-876/v1},
urldate = {2025-06-05},
abstract = {Scientific research relies on computer software, yet software is not always developed following practices that ensure its quality and sustainability. This manuscript does not aim to propose new software development best practices, but rather to provide simple recommendations that encourage the adoption of existing best practices. Software development best practices promote better quality software, and better quality software improves the reproducibility and reusability of research. These recommendations are designed around Open Source values, and provide practical suggestions that contribute to making research software and its source code more discoverable, reusable and transparent. This manuscript is aimed at developers, but also at organisations, projects, journals and funders that can increase the quality and sustainability of research software by encouraging the adoption of these recommendations.},
langid = {english},
language = {en},
keywords = {Praxisregeln,project: documentation,Project: Methods Lab 🥼,Research Software Engineering},
file = {/home/drezil/Zotero/storage/86E3F4DV/Jiménez et al. - 2017 - Four simple recommendations to encourage best practices in research software.pdf}
}
% == BibLateX quality report for JimenezEtAl2017FourSimpleRecommendations:
% ? unused Library catalog ("DOI.org (Crossref)")
@inproceedings{KluyverEtAl2016JupyterNotebookspublishing,
title = {Jupyter {{Notebooks}} a Publishing Format for Reproducible Computational Workflows},
author = {Kluyver, Thomas and Ragan-Kelley, Benjamin and Pérez, Fernando and Granger, Brian and Bussonnier, Matthias and Frederic, Jonathan and Kelley, Kyle and Hamrick, Jessica and Grout, Jason and Corlay, Sylvain and Ivanov, Paul and Avila, Damián and Abdalla, Safia and Willing, Carol and Jupyter development team},
editor = {Loizides, Fernando and Scmidt, Birgit},
namea = {Kluyver, Thomas and Ragan-Kelley, Benjamin and Pérez, Fernando and Granger, Brian and Bussonnier, Matthias and Frederic, Jonathan and Kelley, Kyle and Hamrick, Jessica and Grout, Jason and Corlay, Sylvain and Ivanov, Paul and Avila, Damián and Abdalla, Safia and Willing, Carol and Jupyter development team and Loizides, Fernando and Scmidt, Birgit},
nameatype = {collaborator},
date = {2016},
pages = {87--90},
publisher = {IOS Press},
doi = {10.3233/978-1-61499-649-1-87},
url = {https://eprints.soton.ac.uk/403913/},
urldate = {2025-05-15},
abstract = {It is increasingly necessary for researchers in all fields to write computer code, and in order to reproduce research results, it is important that this code is published. We present Jupyter notebooks, a document format for publishing code, results and explanations in a form that is both readable and executable. We discuss various tools and use cases for notebook documents.},
eventtitle = {20th {{International Conference}} on {{Electronic Publishing}} (01/01/16)},
langid = {english},
language = {en},
keywords = {project: documentation,Project: Methods Lab 🥼},
file = {/home/drezil/Zotero/storage/QB33NJLA/Kluyver et al. - 2016 - Jupyter Notebooks a publishing format for reproducible computational workflows.pdf}
}
% == BibLateX quality report for KluyverEtAl2016JupyterNotebookspublishing:
% Missing required field 'booktitle'
% ? unused Library catalog ("eprints.soton.ac.uk")
@article{Lamprecht2020TowardsFAIRPrinciples,
title = {Towards {{FAIR}} Principles for~Research~Software},
author = {Lamprecht, Anna-Lena and Garcia, Leyla and Kuzak, Mateusz and Martinez, Carlos and Arcila, Ricardo and Martin Del Pico, Eva and Dominguez Del Angel, Victoria and family=Sandt, given=Stephanie, prefix=van de, useprefix=true and Ison, Jon and Martinez, Paula Andrea and McQuilton, Peter and Valencia, Alfonso and Harrow, Jennifer and Psomopoulos, Fotis and Gelpi, Josep Ll. and Chue Hong, Neil and Goble, Carole and Capella-Gutierrez, Salvador},
date = {2020-06-12},
journaltitle = {Data Science},
volume = {3},
number = {1},
pages = {37--59},
publisher = {SAGE Publications},
issn = {2451-8484},
doi = {10.3233/DS-190026},
url = {https://doi.org/10.3233/DS-190026},
urldate = {2025-05-15},
abstract = {The FAIR Guiding Principles, published in 2016, aim to improve the findability, accessibility, interoperability and reusability of digital research objects for both humans and machines. Until now the FAIR principles have been mostly applied to research data. The ideas behind these principles are, however, also directly relevant to research software. Hence there is a distinct need to explore how the FAIR principles can be applied to software. In this work, we aim to summarize the current status of the debate around FAIR and software, as basis for the development of community-agreed principles for FAIR research software in the future. We discuss what makes software different from data with regard to the application of the FAIR principles, and which desired characteristics of research software go beyond FAIR. Then we present an analysis of where the existing principles can directly be applied to software, where they need to be adapted or reinterpreted, and where the definition of additional principles is required. Here interoperability has proven to be the most challenging principle, calling for particular attention in future discussions. Finally, we outline next steps on the way towards definite FAIR principles for research software.},
langid = {english},
language = {EN},
keywords = {project: documentation,Project: Methods Lab 🥼},
file = {/home/drezil/Zotero/storage/CCXUNESS/Lamprecht et al. - 2020 - Towards FAIR principles for research software.pdf}
}
% == BibLateX quality report for Lamprecht2020TowardsFAIRPrinciples:
% Unexpected field 'publisher'
% ? unused Library catalog ("SAGE Journals")
@article{Lee2018Tensimplerules,
title = {Ten Simple Rules for Documenting Scientific Software},
author = {Lee, Benjamin D.},
date = {2018-12-20},
journaltitle = {PLOS Computational Biology},
shortjournal = {PLOS Computational Biology},
volume = {14},
number = {12},
pages = {e1006561},
publisher = {Public Library of Science},
issn = {1553-7358},
doi = {10.1371/journal.pcbi.1006561},
url = {https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1006561},
urldate = {2025-05-15},
langid = {english},
language = {en},
keywords = {Citation analysis,Computer software,Genome analysis,Genomics,Open source software,project: documentation,Project: Methods Lab 🥼,Software development,Software tools,Source code},
file = {/home/drezil/Zotero/storage/Y72BUDFA/Lee - 2018 - Ten simple rules for documenting scientific software.pdf}
}
% == BibLateX quality report for Lee2018Tensimplerules:
% Unexpected field 'publisher'
% ? unused Library catalog ("PLoS Journals")
@article{PrlicProcter2012TenSimpleRules,
title = {Ten {{Simple Rules}} for the {{Open Development}} of {{Scientific Software}}},
author = {Prlić, Andreas and Procter, James B.},
date = {2012-12-06},
journaltitle = {PLOS Computational Biology},
shortjournal = {PLOS Computational Biology},
volume = {8},
number = {12},
pages = {e1002802},
publisher = {Public Library of Science},
issn = {1553-7358},
doi = {10.1371/journal.pcbi.1002802},
url = {https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1002802},
urldate = {2025-05-15},
langid = {english},
language = {en},
keywords = {Computer software,Eyes,Open source software,project: documentation,Project: Methods Lab 🥼,Research funding,Scientists,Software tools,Source code,Sustainability science},
file = {/home/drezil/Zotero/storage/STZFWU4P/Prlić and Procter - 2012 - Ten Simple Rules for the Open Development of Scientific Software.pdf}
}
% == BibLateX quality report for PrlicProcter2012TenSimpleRules:
% Unexpected field 'publisher'
% ? Title looks like it was stored in title-case in Zotero
% ? unused Library catalog ("PLoS Journals")
@article{Smith2016SoftwareCitationPrinciples,
title = {Software Citation Principles},
author = {Smith, Arfon M. and Katz, Daniel S. and Niemeyer, Kyle E.},
date = {2016},
journaltitle = {PeerJ Computer Science},
shortjournal = {PeerJ Comput. Sci.},
volume = {2},
publisher = {PeerJ Inc.},
issn = {2376-5992},
doi = {10.7717/peerj-cs.86},
url = {https://peerj.com/articles/cs-86},
urldate = {2020-09-11},
abstract = {Software is a critical part of modern research and yet there is little support across the scholarly ecosystem for its acknowledgement and citation. Inspired by the activities of the FORCE11 working group focused on data citation, this document summarizes the recommendations of the FORCE11 Software Citation Working Group and its activities between June 2015 and April 2016. Based on a review of existing community practices, the goal of the working group was to produce a consolidated set of citation principles that may encourage broad adoption of a consistent policy for software citation across disciplines and venues. Our work is presented here as a set of software citation principles, a discussion of the motivations for developing the principles, reviews of existing community practice, and a discussion of the requirements these principles would place upon different stakeholders. Working examples and possible technical solutions for how these principles can be implemented will be discussed in a separate paper.},
langid = {english},
language = {en},
keywords = {Eintrag bereinigt,PDF (Dropbox),project: documentation,Project: Methods Lab 🥼,Research Software Engineering},
annotation = {Keine weiteren Informationen gefunden},
file = {/home/drezil/Zotero/storage/XVF927LY/Smith et al. - 2016 - Software citation principles.pdf}
}
% == BibLateX quality report for Smith2016SoftwareCitationPrinciples:
% Unexpected field 'publisher'
% ? unused Library catalog ("peerj.com")
@article{Wilson2017GoodEnoughPractices,
title = {Good Enough Practices in Scientific Computing},
author = {Wilson, Greg and Bryan, Jennifer and Cranston, Karen and Kitzes, Justin and Nederbragt, Lex and Teal, Tracy K.},
date = {2017-06-22},
journaltitle = {PLOS Computational Biology},
shortjournal = {PLOS Computational Biology},
volume = {13},
number = {6},
pages = {e1005510},
publisher = {Public Library of Science},
issn = {1553-7358},
doi = {10.1371/journal.pcbi.1005510},
url = {https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1005510},
urldate = {2025-05-15},
abstract = {Author summary Computers are now essential in all branches of science, but most researchers are never taught the equivalent of basic lab skills for research computing. As a result, data can get lost, analyses can take much longer than necessary, and researchers are limited in how effectively they can work with software and data. Computing workflows need to follow the same practices as lab projects and notebooks, with organized data, documented steps, and the project structured for reproducibility, but researchers new to computing often don't know where to start. This paper presents a set of good computing practices that every researcher can adopt, regardless of their current level of computational skill. These practices, which encompass data management, programming, collaborating with colleagues, organizing projects, tracking work, and writing manuscripts, are drawn from a wide variety of published sources from our daily lives and from our work with volunteer organizations that have delivered workshops to over 11,000 people since 2010.},
langid = {english},
language = {en},
keywords = {Computer software,Control systems,Data management,Metadata,Programming languages,project: documentation,Project: Methods Lab 🥼,Reproducibility,Software tools,Source code},
file = {/home/drezil/Zotero/storage/KWWLZBNY/Wilson et al. - 2017 - Good enough practices in scientific computing.pdf}
}
% == BibLateX quality report for Wilson2017GoodEnoughPractices:
% Unexpected field 'publisher'
% ? unused Library catalog ("PLoS Journals")

View File

@ -0,0 +1,3 @@
.bad-practice {
color: #888888;
}

View File

@ -1,11 +0,0 @@
# Changelog
Dokumentation der Änderungen pro Version:
## [v1.0.0] 2025-05-08
- Erste stabile Version
## [v0.1.0] 2025-03-15
- Erstes öffentliches Release

View File

@ -1,9 +0,0 @@
# Wie wird die Software zitiert?
Nenne hier die bevorzugte Zitierweise für Publikationen oder DOI:
```markdown
Nachname, Vorname. (Jahr). Projektname (Version X.Y.Z). DOI oder URL.
```
- **Keine langen Beschreibungen**, nur den Zitierhinweis.

View File

@ -1,16 +0,0 @@
# Wie beiträgt man zum Projekt?
Anleitung zur Mitarbeit am Projekt.
## Bugs melden & Vorschläge
Wie meldet man Fehler oder schlägt Features vor? (z.B. Issue Tracker)
## Code beisteuern
Richtlinien für Codequalität und Beiträge:
- Wie erstelle ich einen Pull Request?
- Gibt es Stilrichtlinien (z.B. PEP8 für Python)?
- **Nicht überkomplizieren**, sondern klaren Workflow beschreiben.

View File

@ -1,14 +0,0 @@
# Installation
Ausführliche Schritt-für-Schritt Anleitung zur Installation.
## Voraussetzungen
Hier alle Abhängigkeiten (z.B. Python-Version, Pakete, externe Tools) listen.
## Schritte zur Installation
Detaillierte Installationsanweisungen (Code-Blöcke, Terminal-Befehle).
- **Nicht ausführlich Grundlagen erklären**, stattdessen verlinken auf externe
Ressourcen.

View File

@ -1,5 +0,0 @@
MIT License (Beispiel)
Copyright (c) 2025 Name
Permission is hereby granted, free of charge, to any person obtaining a copy...

View File

@ -1,47 +0,0 @@
# Projektname
Kurze Beschreibung (2-3 Sätze), was die Software macht und welches
wissenschaftliche Problem sie löst.
## Ziel / Zweck
Kurz das Ziel oder den Bedarf der Software erläutern.
(Beispiel: „Diese Software analysiert historische Textdaten, um Netzwerke
sozialer Interaktionen zu rekonstruieren.“)
## Installation
Kurz und präzise beschreiben, wie die Software installiert wird (max. 3-5
Schritte).
- Verweise ggf. auf ausführliche `INSTALL.md`
- **Keine ausführliche Erklärung** von Standard-Tools (z.B. Python
installieren), sondern verlinken auf offizielle Seiten
## Nutzung
Minimalbeispiel, wie die Software genutzt wird (kurzer Codeblock oder
Kommandozeilenaufruf mit typischem Input und Output).
- **Nicht zu komplexe Beispiele**, dafür ggf. auf ausführliches Tutorial
(`USAGE.md`) verweisen
## Wissenschaftlicher Hintergrund
Kurze Erklärung der wissenschaftlichen Grundlage (Methode, theoretischer Ansatz)
und Referenzen auf Publikationen oder Quellen.
- **Keine ausführliche Theorie**, diese gehört in Paper oder eigene Datei
(`BACKGROUND.md`)
## Bekannte Einschränkungen
Kurz bekannte Probleme und Limitationen nennen, um Missverständnisse zu
vermeiden.
- **Keine** ausschweifenden technischen Details, sondern praktische Hinweise.
## Lizenz & Zitation
Kurz auf Lizenz verweisen (z.B. „siehe LICENSE“) und erklären, wie das Projekt
zu zitieren ist (z.B. DOI oder Verweis auf `CITATION.md`).

View File

@ -1,15 +0,0 @@
# Nutzung der Software
Ausführliche Beschreibung typischer Workflows oder Beispielanwendungen.
## Beispiele
Detaillierte Schritt-für-Schritt-Anleitungen mit Inputs und Outputs.
Evtl. Screenshots oder Abbildungen zur besseren Verständlichkeit.
- **Keine zu detaillierten technischen Details**, Fokus auf realistische
Anwendungsfälle.
## FAQs (optional)
Häufig auftretende Fragen zur Nutzung kurz und prägnant beantworten.

View File

@ -1,2 +0,0 @@
id,value
1,example
1 id value
2 1 example

View File

@ -1 +0,0 @@
# Hilfsfunktionen

View File

@ -1 +0,0 @@
# Hauptskript

BIN
imgs/use_template_1.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 25 KiB

BIN
imgs/use_template_2.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 89 KiB

BIN
imgs/use_template_3.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 27 KiB

BIN
imgs/use_template_4.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 30 KiB