# How We Work Together

```{eval-rst}
.. verified:: 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

```{eval-rst}
.. list-table::
   :header-rows: 1
   :widths: 20 40 40

   * - 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:**

4. Create a GitHub Issue with the same title
5. Create a feature branch from the issue
6. **Add the GitHub Issue URL to the Meistertask task description**
7. 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:**

3. If it's a lasting architectural or operational decision, migrate it to **Sphinx**
4. 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

```{eval-rst}
.. list-table::
   :widths: 50 50
   :header-rows: 1

   * - 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:

```text
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.