How We Work Together#

✓
Documentation Verified Last checked: 2025-11-20 Reviewer: Christof Buchbender

Welcome! This guide describes how our team collaborates.

Why This Document Exists#

With work spanning hardware, software, operations, and science, we need clarity on where information lives and how we track our work. This prevents:

  • Lost decisions buried in chat history

  • Duplicate work because someone didn’t know a task existed

  • Confusion about where to document something

  • Time wasted searching for information across multiple tools

This is a living document - if something isn’t working, let’s discuss and improve it.

Our Tools at a Glance#

Tool

Purpose

Examples

Meistertask

Single source of truth for all tasks

“Implement authentication API”, “Debug telescope mount issue”, “Review data pipeline performance”

GitHub Issues

Working space for code-related tasks

Duplicate Task from Meistertask when coding is needed; link to Issue in meistertask task

Matrix

Daily communication & quick questions

“Is the test server down?”, “Quick review of this approach?”, “Meeting in 10 mins”

Wiki

Internal notes, drafts, meeting minutes

Meeting notes, brainstorming, work-in-progress ideas, onboarding checklists

Sphinx (this docs)

Official, stable documentation

Architecture decisions, API documentation, deployment procedures, user guides

Email

External communication

Communicating with collaborators, institutions, vendors

Common Workflows#

Starting a New Task#

  1. Create a task in Meistertask on the appropriate board (Data Center, Transfer, Pipeline, etc.) with a clear title and description

  2. Assign it to yourself (or the appropriate person)

  3. Add relevant tags/labels and due dates if applicable

If the task involves writing or modifying code:

  1. Create a GitHub Issue with the same title

  2. Create a feature branch from the issue

  3. Add the GitHub Issue URL to the Meistertask task description

  4. Work in the branch, reference the issue in commits

Note

The GitHub Issue is your working space for code review and technical discussion. Meistertask remains the source of truth for task status and assignment.

When Code is Merged#

  1. Merge your PR and close the GitHub Issue

  2. Manually mark the Meistertask task as complete

  3. Update relevant Sphinx documentation if the change affects user-facing behavior or architecture

Warning

Tasks do not auto-close. You must update Meistertask yourself to keep tracking accurate.

Documenting Decisions#

During a meeting or discussion:

  1. Take notes in Matrix chat or directly in the Wiki

  2. Include: decision made, rationale, who was involved, date

After the decision solidifies:

  1. If it’s a lasting architectural or operational decision, migrate it to Sphinx

  2. Link from the Wiki note to the Sphinx page (so context is preserved)

Rule of thumb: If someone joining in 6 months would need to know this, it belongs in Sphinx.

Asking Questions#

Question Type

Where to Ask

Quick clarification, “Does anyone know…?”

Matrix

Question about a specific task

Meistertask task description/comments

Technical discussion about a specific PR/code change

GitHub Issue comments

Longer discussion needing decisions

Schedule a meeting, document outcome in Wiki → Sphinx

What Goes Where?#

Still not sure where something belongs? Use this decision tree:

Is it a TASK (something someone needs to do)?
└─→ Meistertask
    └─→ Does it need code changes?
        └─→ YES: Also create GitHub Issue + branch
        └─→ NO: Just Meistertask is fine

Is it a CONVERSATION?
└─→ Quick question/update? → Matrix
└─→ Question about a specific task? → Meistertask task description/comments
└─→ Needs external people? → Email
└─→ Technical code discussion? → GitHub Issue

Is it DOCUMENTATION?
└─→ Meeting notes, brainstorming, WIP? → Wiki
└─→ Stable, needs to be found later? → Sphinx
└─→ Temporary context for a task? → Meistertask task description

What NOT to Do#

❌ Don’t track tasks only in GitHub Issues - They won’t be visible to non-code work, and extended team members may not check GitHub regularly

❌ Don’t make important decisions only in Matrix - Chat history gets buried. Document decisions in Wiki (then Sphinx if permanent)

❌ Don’t duplicate content between Wiki and Sphinx - Link instead. The Wiki can say “See [Sphinx page] for details”

❌ Don’t leave GitHub Issues open after merging - Close them and update the Meistertask task

Managing Wiki Content#

The Wiki is for fluid, working content. To prevent it from becoming a graveyard:

Content Types and Lifespans:

  • Meeting notes: Keep for 3-6 months, then archive or delete if not referenced

  • Brainstorming/drafts: Either move to Sphinx when ready, or delete if abandoned

  • Onboarding materials: Review every 6 months, update or remove outdated info

Responsibilities:

  • If you create a Wiki page, you’re responsible for its lifecycle

  • Add a “Last reviewed: [date]” to important pages

  • During quarterly reviews, we’ll identify stale content together

Tip

When in doubt: Start in Wiki, promote to Sphinx when it’s ready for others to rely on.

Questions & Improvements#

This workflow will evolve as we learn what works for our team.

  • Something unclear? Ask in Matrix and we’ll clarify here

  • Process not working? Let’s discuss and adjust

  • Found a better way? Propose a change to this doc

Our goal is effectiveness, not bureaucracy.