mirror of
https://scm.cms.hu-berlin.de/methodenlabor/doc_documentation.git
synced 2025-06-14 12:39:07 +00:00
Compare commits
8 Commits
5172700f0b
...
9793c6450e
| Author | SHA1 | Date | |
|---|---|---|---|
|
9793c6450e | ||
|
|
11af56ddf8 | ||
|
|
0f35cd6a04 | ||
|
3cb8457bc8 | ||
|
|
a601ada928 | ||
|
|
e41d3c4c3e | ||
|
|
f54c779f9f | ||
|
|
89ab2f39c2 |
39
.gitlab/changelog_config.yml
Normal file
39
.gitlab/changelog_config.yml
Normal 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+)$'
|
||||
26
.gitlab/issue_templates/Bug.md
Normal file
26
.gitlab/issue_templates/Bug.md
Normal 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"
|
||||
90
.gitlab/issue_templates/Conference_Knowledge_Sharing.md
Normal file
90
.gitlab/issue_templates/Conference_Knowledge_Sharing.md
Normal 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._
|
||||
27
.gitlab/issue_templates/Decision Matrix.md
Normal file
27
.gitlab/issue_templates/Decision Matrix.md
Normal 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:"
|
||||
3
.gitlab/issue_templates/Default.md
Normal file
3
.gitlab/issue_templates/Default.md
Normal 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.
|
||||
125
.gitlab/issue_templates/Deprecations.md
Normal file
125
.gitlab/issue_templates/Deprecations.md
Normal 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"
|
||||
285
.gitlab/issue_templates/Design Sprint.md
Normal file
285
.gitlab/issue_templates/Design Sprint.md
Normal 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 We’s (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, we’ll 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 you’d 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 you’ll 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/> • It’s 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!
|
||||
44
.gitlab/issue_templates/Documentation.md
Normal file
44
.gitlab/issue_templates/Documentation.md
Normal 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
|
||||
41
.gitlab/issue_templates/Experiment Idea.md
Normal file
41
.gitlab/issue_templates/Experiment Idea.md
Normal 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 we’ll 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 doesn’t 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 we’re 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, we’re hoping our experiment will ... but we’re 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"
|
||||
25
.gitlab/issue_templates/Experiment Implementation.md
Normal file
25
.gitlab/issue_templates/Experiment Implementation.md
Normal 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 |
|
||||
| -------- | -------- | ------ | ----- |
|
||||
| | | | |
|
||||
10
.gitlab/issue_templates/Feature Proposal - basic.md
Normal file
10
.gitlab/issue_templates/Feature Proposal - basic.md
Normal 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
|
||||
17
.gitlab/issue_templates/Feature Proposal - lean.md
Normal file
17
.gitlab/issue_templates/Feature Proposal - lean.md
Normal 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"
|
||||
44
.gitlab/issue_templates/Feature proposal - detailed.md
Normal file
44
.gitlab/issue_templates/Feature proposal - detailed.md
Normal 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"
|
||||
37
.gitlab/issue_templates/Implementation.md
Normal file
37
.gitlab/issue_templates/Implementation.md
Normal 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
|
||||
25
.gitlab/issue_templates/Refactoring.md
Normal file
25
.gitlab/issue_templates/Refactoring.md
Normal 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"
|
||||
66
README.md
66
README.md
@ -12,29 +12,57 @@ 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.
|
||||
|
||||
1. Neues Projekt erstellen
|
||||
|
||||
2. Aus Template
|
||||
|
||||
3. Gruppe wählen
|
||||
|
||||
4. Template auswählen & erstellen
|
||||
|
||||
|
||||
### 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.
|
||||
|
||||
Das Template enthält folgende Struktur:
|
||||
|
||||
```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
|
||||
.
|
||||
├── .gitlab (issue-templates für GitLab)
|
||||
├── CHANGELOG.md (CHANGELOG-Beispiel für Releases)
|
||||
├── CITATION.md (Wie die Software zitieren?)
|
||||
├── CONTRIBUTING.md (Wie bei der Software mithelfen?)
|
||||
├── INSTALL.md (Wie die Software installieren?)
|
||||
├── README.md (Genereller Überblick)
|
||||
├── src (Beispielverzeichnis für den eigentlichen Code)
|
||||
└── USAGE.md (Wie nutze ich die Software?)
|
||||
```
|
||||
|
||||
Die jeweiligen benötigten Dateien können einfach kopiert werden und enthalten
|
||||
jeweils eine Anleitung über ihren Inhalt
|
||||
Die Dateien enthalten jeweils eine Anleitung über ihren Inhalt
|
||||
|
||||
### Daten-Project
|
||||
|
||||
**Ein ähnliches Projekt für Daten-Repositories ist in Planung.**
|
||||
|
||||
Das Template ist für Repositories gedacht, die Daten aus Quellen erstellen,
|
||||
aufbereiten und wieder zur Verfügung stellen. Beispiele wären z.b. Bilder ~>
|
||||
annotierter Korpus.
|
||||
|
||||
Ziel ist hier die Dokumentation und die Reproduzierbarkeit von
|
||||
`Quelle -> Datensatz`.
|
||||
|
||||
## Wissenschaftlicher Hintergrund
|
||||
|
||||
|
||||
@ -71,15 +71,15 @@ gute Dokumentation als zentrale Voraussetzung, um Forschungssoftware
|
||||
**auffindbar, nachvollziehbar und wiederverwendbar** zu machen.
|
||||
|
||||
[Alle Empfehlungen stützen sich auf Literatur und etablierte Richtlinien
|
||||
[@prlic2012ten; @wilson2017good; @katz2021open;
|
||||
@endings2020principles].]{.aside}
|
||||
[@PrlicProcter2012TenSimpleRules; @WilsonEtAl2017Goodenoughpractices; @BarkerEtAl2022IntroducingFAIR;
|
||||
@EndingsPrinciples221].]{.aside}
|
||||
|
||||
Dieser Anforderungskatalog richtet sich an Forschende, die keine
|
||||
Vollzeit-Programmierer sind, und soll **wissenschaftlich fundierte Richtlinien**
|
||||
für die Dokumentation von Forschungssoftware liefern. Die Empfehlungen
|
||||
berücksichtigen Best Practices des Research Software Engineering (RSE) und
|
||||
insbesondere die Prinzipien des _Endings-Projekts_ für digitale Langlebigkeit
|
||||
[@endings2020principles]. Ziel ist es, ein praxistaugliches Gerüst
|
||||
[@EndingsPrinciples221]. Ziel ist es, ein praxistaugliches Gerüst
|
||||
bereitzustellen, das – trotz Zeitknappheit – die wesentlichen
|
||||
Dokumentationsaspekte abdeckt, um sowohl die **Nachvollziehbarkeit** der
|
||||
Ergebnisse als auch eine **Weiterverwendung** der Software zu ermöglichen. Im
|
||||
@ -221,7 +221,7 @@ Nachnutzung nicht zu behindern. Zudem sollte angegeben werden, wie die Software
|
||||
_“Zitation”_ oder eine CITATION-Datei beschreibt, welche Publikation oder
|
||||
welcher DOI bei Verwendung der Software in wissenschaftlichen Arbeiten anzugeben
|
||||
ist. Dies erhöht die akademische Sichtbarkeit und stellt sicher, dass
|
||||
Autor\*innen Credits für ihre Software bekommen[@smith2016software]. Schließlich
|
||||
Autor\*innen Credits für ihre Software bekommen [@SmithEtAl2016Softwarecitation]. Schließlich
|
||||
ist es sinnvoll, eine **Versionsnummer** der Software zu nennen (idealerweise in
|
||||
README und im Tool selbst), damit Nutzer wissen, auf welche Ausgabe sich die
|
||||
Dokumentation bezieht – insbesondere, wenn es im Laufe der Zeit Aktualisierungen
|
||||
@ -505,7 +505,7 @@ und Einheitlichkeit zu gewährleisten.
|
||||
### Jupyter Notebooks und literate programming
|
||||
|
||||
Ein mächtiges Werkzeug – gerade in datengetriebenen Geisteswissenschaften – sind
|
||||
**Jupyter Notebooks** bzw. R Markdown Notebooks [@maria2019jupyter]. Diese
|
||||
**Jupyter Notebooks** bzw. R Markdown Notebooks [@KluyverEtAl2016JupyterNotebookspublishing]. Diese
|
||||
erlauben es, _ausführbaren Code mit erklärendem Text und Visualisierungen_ in
|
||||
einem Dokument zu vereinen. Für Dokumentationszwecke können Notebooks zweierlei
|
||||
leisten: (1) als **Tutorials/Beispiel-Workflows**, die Nutzer interaktiv
|
||||
|
||||
@ -1,69 +1,231 @@
|
||||
@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}
|
||||
% this bibliography is maintained in Zotero with the tag 'project: documentation'
|
||||
% prefered format is BibLaTeX
|
||||
|
||||
@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},
|
||||
keywords = {field: History,project: documentation,Project: Methods Lab 🥼}
|
||||
}
|
||||
|
||||
@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},
|
||||
keywords = {Digital Scholarly Editions,project: documentation,Project: Methods Lab 🥼,TEI: Text Encoding Initiative}
|
||||
}
|
||||
|
||||
@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},
|
||||
keywords = {project: documentation,Project: Methods Lab 🥼,RSE: Research Software Engineering}
|
||||
}
|
||||
|
||||
@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},
|
||||
keywords = {field: Digital Humanities (DH),Project management,project: documentation,Project: Methods Lab 🥼}
|
||||
}
|
||||
|
||||
@misc{endings2020principles,
|
||||
title = {Endings Principles for Digital Longevity},
|
||||
author = {{Endings Project}},
|
||||
year = {2020},
|
||||
url = {https://endings.uvic.ca/principles.html}
|
||||
@article{DiehlEtAl2025JournalOpenSource,
|
||||
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 JOSS’s history and its peer review process using an editorial bot, and we present statistics gathered from JOSS’s 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: JOSS’s process differs significantly from traditional journals, which has impeded JOSS’s inclusion in indexing services such as Web of Science. In turn, this discourages researchers within certain academic systems, such as Italy’s, 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},
|
||||
keywords = {project: documentation,Project: Methods Lab 🥼}
|
||||
}
|
||||
|
||||
@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},
|
||||
version = {2.2.1},
|
||||
keywords = {project: documentation,Project: Methods Lab 🥼,Project: Tool Registry 🧰,talk: 2024 Bochum,writing: 2024 Tool Registry}
|
||||
}
|
||||
|
||||
@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},
|
||||
version = {1.2},
|
||||
keywords = {project: documentation,Project: Methods Lab 🥼}
|
||||
}
|
||||
|
||||
@book{Kemman2021Trading,
|
||||
title = {Trading {{Zones}} of {{Digital History}}},
|
||||
author = {Kemman, Max},
|
||||
date = {2021},
|
||||
series = {Studies in {{Digital History}} and {{Hermeneutics}}},
|
||||
number = {1},
|
||||
publisher = {De Gruyter Oldenbourg},
|
||||
location = {Berlin, Boston},
|
||||
doi = {10.1515/9783110682106},
|
||||
url = {https://www.degruyter.com/document/doi/10.1515/9783110682106/html},
|
||||
urldate = {2021-09-23},
|
||||
abstract = {Digital history is commonly argued to be positioned between the traditionally historical and the computational or digital. By studying digital history collaborations and the establishment of the Luxembourg Centre for Contemporary and Digital History, Kemman examines how digital history will impact historical scholarship. His analysis shows that digital history does not occupy a singular position between the digital and the historical. Instead, historians continuously move across this dimension, choosing or finding themselves in different positions as they construct different trading zones through cross-disciplinary engagement, negotiation of research goals and individual interests.},
|
||||
isbn = {978-3-11-068210-6},
|
||||
langid = {english},
|
||||
pagetotal = {182},
|
||||
keywords = {Digital History,Eintrag bereinigt,PDF (Dropbox),project: documentation,TH-MA-Bloomsbury}
|
||||
}
|
||||
|
||||
@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},
|
||||
keywords = {project: documentation,Project: Methods Lab 🥼}
|
||||
}
|
||||
|
||||
@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}
|
||||
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},
|
||||
keywords = {project: documentation,Project: Methods Lab 🥼}
|
||||
}
|
||||
|
||||
@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},
|
||||
keywords = {project: documentation,Project: Methods Lab 🥼}
|
||||
}
|
||||
|
||||
@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},
|
||||
keywords = {project: documentation,Project: Methods Lab 🥼}
|
||||
}
|
||||
|
||||
@article{SmithEtAl2016Softwarecitation,
|
||||
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},
|
||||
keywords = {Eintrag bereinigt,PDF (Dropbox),project: documentation,Project: Methods Lab 🥼,Research Software Engineering}
|
||||
}
|
||||
|
||||
@article{WilsonEtAl2017Goodenoughpractices,
|
||||
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},
|
||||
keywords = {project: documentation,Project: Methods Lab 🥼}
|
||||
}
|
||||
|
||||
@ -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
|
||||
@ -1,19 +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.
|
||||
```
|
||||
|
||||
```bibtex
|
||||
@software{bibtex-key,
|
||||
author = {{}},
|
||||
title = {Projektname},
|
||||
url = {Projekthomepage},
|
||||
version = {version},
|
||||
date = {datum versions-release},
|
||||
}
|
||||
```
|
||||
|
||||
- **Keine langen Beschreibungen**, nur den Zitierhinweis.
|
||||
@ -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.
|
||||
@ -1,18 +0,0 @@
|
||||
---
|
||||
date: 2025-05-14 # when was this touched last?
|
||||
---
|
||||
|
||||
# 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.
|
||||
@ -1,5 +0,0 @@
|
||||
MIT License (Beispiel)
|
||||
|
||||
Copyright (c) 2025 Name
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy...
|
||||
@ -1,161 +0,0 @@
|
||||
---
|
||||
title: "<Projektname>"
|
||||
description: |
|
||||
Kurze Beschreibung (2-3 Sätze), was die Software macht und welches wissenschaftliche Problem sie löst.
|
||||
lang: de
|
||||
date: 2025-05-14
|
||||
authors:
|
||||
- name: Your Name
|
||||
affiliation:
|
||||
- name: Your Institution
|
||||
url: Institutions homepage
|
||||
email: your@email.here
|
||||
orcid: 0000-0000-0000-0000
|
||||
roles: # CRediT-Roles - see https://credit.niso.org/
|
||||
- Conceptualization
|
||||
- Supervision
|
||||
- Validation
|
||||
# ... weitere Autor*innen
|
||||
---
|
||||
|
||||
Auf Wunsch Beschreibung noch einmal wiederholen
|
||||
|
||||
## Über dieses Repository
|
||||
|
||||
### Ziel / Zweck
|
||||
|
||||
Kurz das Ziel oder den Bedarf der Software erläutern.
|
||||
(Beispiel: „Diese Software analysiert historische Textdaten, um Netzwerke
|
||||
sozialer Interaktionen zu rekonstruieren.“)
|
||||
|
||||
Ist die Software noch in Entwicklung? Abgeschlossen? Abgebrochen?
|
||||
|
||||
### Installation
|
||||
|
||||
Kurz und präzise beschreiben, wie die Software installiert wird (max. 3-5
|
||||
Schritte).
|
||||
|
||||
- Verweise ggf. auf ausführliche [INSTALL.md](INSTALL.md)
|
||||
|
||||
> [!warning]
|
||||
>
|
||||
> **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).
|
||||
|
||||
> [!warning]
|
||||
>
|
||||
> **Nicht zu komplexe Beispiele**, dafür ggf. auf ausführliches Tutorial (Datei
|
||||
> [USAGE.md](USAGE.md) oder Verzeichnis [examples/](examples/)) verweisen
|
||||
|
||||
### Bekannte Einschränkungen
|
||||
|
||||
Kurz bekannte Probleme und Limitationen nennen, um Missverständnisse zu
|
||||
vermeiden.
|
||||
|
||||
> [!warning]
|
||||
>
|
||||
> **Keine** ausschweifenden technischen Details, sondern praktische Hinweise.
|
||||
|
||||
### Struktur
|
||||
|
||||
```plain
|
||||
Übersicht der Struktur z.b. generiert mittels
|
||||
`tree -L2` oder `tree -L2 -d`
|
||||
und anschließend überarbeitet
|
||||
```
|
||||
|
||||
- Kurze Beschreibung - entweder direkt im Tree oder hier in Prosa
|
||||
- Ziel: Überblick über "Wo finde ich was". Wo ist Doku? Wo ist Code? Wo ist ...?
|
||||
|
||||
> [!warning]
|
||||
>
|
||||
> **Keine Details**, die über 1 Satz pro Element hinaus gehen. Bei detailliertem
|
||||
> Bedarf `README.md` im jeweiligen Verzeichnis.
|
||||
|
||||
## Meta-Informationen
|
||||
|
||||
### Verantwortlichkeiten
|
||||
|
||||
- Wer ist letztendlich verantwortlich für den Inhalt?
|
||||
- Wer genehmigt/weist Inhalte ab?
|
||||
|
||||
### Wissenschaftlicher Hintergrund
|
||||
|
||||
Kurze Erklärung der wissenschaftlichen Grundlage (Methode, theoretischer Ansatz)
|
||||
und Referenzen auf Publikationen oder Quellen.
|
||||
|
||||
> [!warning]
|
||||
>
|
||||
> **Keine ausführliche Theorie**, diese gehört in Paper oder eigene Datei
|
||||
> ([BACKGROUND.md](BACKGROUND.md))
|
||||
|
||||
### 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](CITATION.md)).
|
||||
|
||||
---
|
||||
|
||||
## Empfohlene Dokumentations-Dateien
|
||||
|
||||
| **Dokuelement** | **Inhalt/Purpose** | **Format/Ort** | **Umfang** |
|
||||
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | ------------------------------------- |
|
||||
| **README (Hauptdoku)** | Zweck der Software; Kurzbeschreibung; Installationsanleitung; einfaches Nutzungsbeispiel; Lizenz- und Kontaktinfo | Markdown im Root des Repos (statisch versioniert) | 1–2 Seiten |
|
||||
| **Eingabe/Ausgabe-Guide** | Beschreibung der erwarteten Inputs (Datenformat, Parameter) und generierten Outputs (Dateien, Berichte) inkl. Beispielen | Teil der README oder separate Datei (z.B. USAGE.md) | 1 Seite (mit Beispielen) |
|
||||
| **Wissenschaftlicher Hintergrund** | Erläuterung der Methode, Theorie, Algorithmen; Verweise auf Literatur | README-Abschnitt "Hintergrund" oder separate Doku (BACKGROUND.md) | 0.5–1 Seite (plus Referenzen) |
|
||||
| **Bekannte Limitationen** | Auflistung von Einschränkungen, Annahmen, bekannten Problemen; ggf. Workarounds | README-Abschnitt "Limitations" oder FAQ.md | 0.5 Seite |
|
||||
| **Beispiel-Workflow (Tutorial)** | Schritt-für-Schritt Anleitung mit einem realistischen Anwendungsfall (ggf. mit Code und Screenshot) | Jupyter Notebook (`.ipynb`) im Repo `examples/` Ordner oder Markdown in docs/ | 1–3 Seiten / entsprechend Zellen |
|
||||
| **API-Referenz** | Technische Dokumentation von Funktionen/Klassen für Entwickler\*innen | Automatisch generiert aus Docstrings (z.B. Sphinx in `docs/` Ordner, HTML/PDF Ausgabe) | Je nach Codegröße (ggf. umfangreich) |
|
||||
| **CONTRIBUTING** | Anleitung für Beitragswillige: Code Style, Workflow, Tests, Kontakt | CONTRIBUTING.md im Repo | 0.5–1 Seite |
|
||||
| **LICENSE** / **CITATION** | Rechtliche Infos (Lizenztext); Zitationsleitfaden (Bevorzugte Zitierweise, DOI) | Jeweils eigene Datei im Repo (Plain Text/Markdown) | Kurz (Standardtext bzw. Referenz) |
|
||||
| **Release-Information** | Versionshinweise, Änderungsprotokoll (Changelog) | CHANGELOG.md oder Releases auf GitHub | fortlaufend pro Version (Stichpunkte) |
|
||||
|
||||
## Checklist
|
||||
|
||||
Es ist eine gute Idee die sich ändernden Punkte in ein Release-Template zu
|
||||
kopieren.
|
||||
|
||||
- [ ] **Zielklärung:** Ist der Zweck der Software klar benannt und der
|
||||
wissenschaftliche _Need_ begründet? (Falls nein, ergänzen: _Warum
|
||||
existiert dieses Tool?_)
|
||||
- [ ] **Installation & Voraussetzungen:** Sind alle Schritte, um die Software
|
||||
lauffähig zu machen, dokumentiert (inkl. Dependencies, evtl. mit
|
||||
Installationsbefehlen)? Ist ersichtlich, welche Umgebung nötig ist (OS,
|
||||
Hardware)?
|
||||
- [ ] **Grundlegende Nutzung:** Gibt es eine Anleitung oder Beispiele, wie man
|
||||
die Software verwendet (Eingabe -> Ausgaben)? Ist mindestens ein typischer
|
||||
Workflow beschrieben, idealerweise mit Beispielinput und -output?
|
||||
- [ ] **Optionen & Schnittstellen:** Falls relevant – sind alle wichtigen
|
||||
Funktionen, Befehlsoptionen oder API-Methoden dokumentiert? (Nicht
|
||||
unbedingt jede intern, aber alles, was ein Nutzer aufrufen könnte). Für
|
||||
APIs: Sind Parameter und Rückgaben erläutert?
|
||||
- [ ] **Validierung & Einschränkungen:** Werden Annahmen und Grenzen der
|
||||
Software genannt? Weiß ein*e Nutzer*in, welche Fälle nicht abgedeckt sind
|
||||
oder worauf zu achten ist (z. B. Datenqualität, maximale Größen)?
|
||||
Transparenz hier verhindert Frustration.
|
||||
- [ ] **Hintergrund & Referenzen:** Sind die wichtigsten konzeptionellen
|
||||
Hintergründe oder Referenzen angegeben? (Z. B. theoretische Grundlagen,
|
||||
Algorithmen, Literaturverweise). Das muss kein Essay sein, aber ein paar
|
||||
Sätze + Referenzen schaffen Vertrauen in die wissenschaftliche Fundierung.
|
||||
- [ ] **Kontakt & Weiterführung:** Ist angegeben, wie man Hilfe bekommt oder
|
||||
Fehler melden kann (Issue-Tracker, E-Mail)? Gibt es Hinweise für Beiträge
|
||||
(falls erwünscht) oder zumindest die Information, wer die Autor\*innen
|
||||
sind?
|
||||
- [ ] **Rechtliches & Zitation:** Liegt die Lizenz bei und wird sie genannt?
|
||||
Sind Infos zum Zitieren der Software vorhanden (z. B. “Bitte zitieren Sie
|
||||
DOI XYZ”)? Das stellt sicher, dass die Software nachnutzbar _und_
|
||||
akademisch kreditiert wird.
|
||||
- [ ] **Aktualität & Version:** Entspricht die Dokumentation der aktuellen
|
||||
Softwareversion? (Check: Versionsnummern, Datumsangaben). Veraltete Doku
|
||||
kann schlimmer sein als keine – planen Sie also ein, die Doku mit jedem
|
||||
Release kurz zu überprüfen.
|
||||
- [ ] **Konsistenz & Stil:** Wird ein einheitlicher Ton und Stil durchgehalten?
|
||||
(z. B. durchgehende Verwendung gleicher Begriffe für Konzepte, Sprache
|
||||
entweder Deutsch oder Englisch einheitlich je nach Zielgruppe). Kleinliche
|
||||
Fehler (Tippfehler, kaputte Links) sind auszumerzen, da sie Nutzer
|
||||
abschrecken.
|
||||
@ -1,19 +0,0 @@
|
||||
---
|
||||
title: "Nutzung der Software"
|
||||
date: 2025-05-14 # zuletzt angepasst
|
||||
version: v1.0 # Auf welche Version bezieht sich dies?
|
||||
---
|
||||
|
||||
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.
|
||||
@ -1,2 +0,0 @@
|
||||
id,value
|
||||
1,example
|
||||
|
@ -1 +0,0 @@
|
||||
# Hilfsfunktionen
|
||||
@ -1 +0,0 @@
|
||||
# Hauptskript
|
||||
BIN
imgs/use_template_1.png
Normal file
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
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
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
BIN
imgs/use_template_4.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 30 KiB |
Loading…
x
Reference in New Issue
Block a user