We use a GitHub repository for project and knowledge management

We don’t use Microsoft Teams, Slack, or any other fancy corporate productivity tool for project and knowledge management in our research group. 🤯 Shocking, I know!

Instead, we use a simple GitHub repository, and here is how we do it:

The GitHub repository is the single place where the lab and everything that relates to it is documented. No dropboxes, no Google docs, no Google calendar, no information that only exists in our e-mail inboxes, etc. In general, we try to avoid scattering information across multiple different platforms and instead try to collect everything in this repository, our single source of truth.

We use three components of the GitHub repository:

  1. The issue tracker
  2. The wiki
  3. The git file repository.

At this time, we do not use pull requests, actions, and projects. But these may become useful once the group is bigger and when we work on more complex projects.

The issue tracker serves two purposes:

  1. We use it to organize our work, to discuss, and to track progress on individual tasks.
  2. It serves as a record and documentation for the future.

The wiki is a store of knowledge for our future selves and new lab members. This includes technical documentation, guidelines, meeting notes, consent forms, templates, instructions for participants, etc.

The git file repository is used for code (analysis scripts, experiment templates, etc.), data, and documents that contain information that can't be stored in the wiki, e.g., because it needs to be in a specific file format.

Details and specific guidelines below.

Issue Tracker

Here's how we use the issue tracker:

  • Don’t hesitate to create new issues. But avoid duplicates. As a general rule, all non-trivial tasks should have an issue, especially if they require discussion and if they can't be dealt with immediately.
  • When you create an issue:
    • Make sure it corresponds to a single, clearly-defined task.
    • The title of the issue should clearly describe the task and ideally start with a verb, e.g: Write guidelines for XYZ
    • The description of the task should be concise but detailed enough so that someone else could address it without your input.
  • Assign every issue to someone. Unassigned issues risk falling through the cracks or not being addressed in time. Encourage re-assignment if necessary.
  • Select a milestone, if relevant, to attribute deadlines automatically. Feel free to create new milestones but make sure they’re not redundant or too fine-grained. Managing milestones should not itself become task.
  • Optionally, assign labels (e.g., administration, lab, teaching). Keep labels few and high-level for simplicity.
  • Upon closing an issue, review the discussion for reusable information and add it to the wiki if needed.
  • @mention collaborators for input.
  • Refer to related issues by their ID, e.g., #9.
  • Keep discussions focused. Avoid using the tracker for personal communication or irrelevant topics.

Wiki

The wiki serves multiple purposes:

  1. Help with onboarding new members.
  2. Standardize workflows to reduce friction.
  3. Document and improve workflows to enhance productivity and robustness of research artifacts.
  4. Explicitly state our goals and values.

Specific guidance:

  • Use short, memorable names for wiki pages, e.g., ConsentEyeTracking
  • Use CamelCase for wiki names based on specific content words.
  • For related topics, use parallel names, e.g: ConsentEyeTracking and ConsentWebStudies
  • Example page title: How we manage consent in eye-tracking studies (Template: How we VERB XYZ)

  • How-to pages should include:

    1. Goals
    2. Principles that we apply to reach those goals
    3. Concrete guidance on how to implement these principles

    The goals are usually fixed, the principles change rarely, but the
    concrete implementation can change often (as we learn how to do
    things more effectively). That’s one motivation for keeping these
    three things separate.

  • Do not attach files to wiki pages unless they are hyper-specific to the page. Otherwise, use the git repo and link files.
  • Consider inlining content (e.g., consent forms) instead of creating separate files for simplicity.
  • Fix outdated or incomplete content immediately when you see it.

Git File Repository

We haven’t yet established clear conventions for the file repository.
Open questions include:

  • File naming conventions
  • Directory structure
  • Which file types to include/avoid
  • What information to store here vs. in the wiki

Happy to hear everyone’s thoughts on this and everything else?