============================
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
=====================

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

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

.. list-table::
   :widths: 50 50
   :header-rows: 1

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

.. code-block:: 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
   └─→ 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]*