How We Work Together

Welcome! This guide describes how our team collaborates across the diverse range of projects we handle - from telescope hardware and data pipelines to APIs and science publications.

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

Created from Meistertask when coding is needed; links back to parent 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 with a clear title and description

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

  3. Add relevant tags/labels for the work area (hardware, backend, data-ops, etc.)

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

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
└─→ 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.

Last updated: [2025-10-13] Document owner: [Christof Buchbender]