Workflow - jonathancolmer/lab-guide GitHub Wiki

This page outlines the tools we use and how we use them. All team members are expected to follow this workflow.

Screenshot 2025-05-18 at 1 39 57 AM

Communication and Coordination

Slack (Communication & Ideas)

Slack is our main tool for communication.

Why Slack?

  • It streamlines communications and is less formal than email.
  • It supports file sharing and integrations.
  • It offers a searchable message history and threaded discussions.

How we use it:

  • Use channels for topic-specific discussions (e.g., #general, #research, #projectQ).
  • Use DMs for quick clarifications.
  • Share early-stage ideas, links, or quick questions.
  • Use threads to maintain organized, searchable conversations.
  • Each post should contain one point or question so we can thread discussions effectively.
  • Speak face-to-face when it is possible and more efficient to do so.

Todoist (Task Management)

This is the tool we use for organizing and tracking tasks.

  • Write your tasks including self-assigned and adjustable deadlines and priorities.
  • Jonathan may assign tasks to you as well, but most of the time you are responsible for posting tasks.
  • Break larger tasks into subtasks.
  • Use comments to share updates and attach files.
  • When a task is finished create a task and assign it to Jonathan to look at the work and sign off.
  • Track your own work on your personal board.

Code and Analysis

Software

  • We primarily use R and Stata.
  • We occasionally use Python.
  • Clear, organized, commented code is necessary whatever language is being used.
  • "Dear reader" README files should be created for each script.

IDE: VS Code

You should use VS Code for writing and managing code across languages.

  • It is a unified environment that supports R, Python, Stata, LaTeX, Markdown, and Git integration.
  • You may also want to explore Cursor, an AI-enhanced version of VS Code.

Version Control: Git + GitHub

Version control is essential to our workflow. It allows us to track changes to code and documents over time, maintain a full history of edits and collaborations, and enable reproducibility and transparency. We use Git and GitHub to manage all code and documentation.

Our workflow follows a simplified GitHub Flow:

  1. Create a branch
  • Use a clear name (e.g., fix-import-errors, issue-23-summary-figures)
  • Work on your task
  • Use commits to document progress
  1. Open a pull request
  • Assign reviewers and yourself
  • Reviewers check clarity, reproducibility, and standards
  • Once approved, merge to main and delete the branch

File Management and Documentation

Dropbox (File and Data Storage)

We use Dropbox to store and organize all non-code research-related files. Dropbox is helpful because it allows:

  • Cross-device access
  • Real-time syncing
  • Version history
  • Secure sharing

Dropbox is used for structured storage:

  • Raw data
  • Processed data
  • Output (figures, tables)
  • Final products (papers, slides, supplements)

Ensure files are saved in shared, organized, and logically named folders.

LaTeX + Overleaf (Writing)

We use LaTeX for scientific writing, typically through Overleaf. It is a widely used typesetting system due to its powerful handling of formulas and citations.

We use it for:

  • Drafting research papers, reports, and presentations.
  • Writing and formatting equations, tables, and figures.
  • Collaborative editing.

Plain Text:

R, Stata, LaTeX, Python, and Git have a shared foundation --- plain text.

Plain text files are simple, unformatted files that power reproducible research. They are universally accessible in any basic text editor.

We use plain text because it is:

  • portable, future-proof, and version-controllable.
  • lightweight and storage-efficient.

Please do not use Microsoft Office products.