DEV Community: Natik Gadzhi

Remote Team Health Check

Natik Gadzhi — Mon, 03 Jul 2023 21:58:06 +0000

I've been away from my team for almost a month and a half. No checking-in on Slack, no reading weekly posts on Basecamp. I didn't know what was happening, and of course, I was anxious about it.

We're a fully remote company, and every time I get back from time off, I scan for how the team is feeling. You can usually scan your team's communication channels in just a few minutes to get a picture of whether the team is happy, motivated, and productive, or stressed, burned out, and confused.

Here's the list of things I look for to get that picture. Your list may vary: each team has their own culture, so their "happy place" will be different. But the principle stays the same — quick scan to see where your attention is needed most.

Are people working in the open?

Do you see folks talking about their day-to-day work in the open Slack channels (or Discord, or whatever else you use)? Asking for a review, syncing up between platform and product, frontend and backend engineers, quick asks about different pieces of your system, or product or design questions — do you see them in the open?

Working in the open channels is essential (to me) in remote environments: it lets others chime in, understand how things work, see the progress, or search for that topic in the future, or support the work if the team needs help, or if someone has a few days off, and someone else is picking up their work.

If you don't see open chatter — it's either because no one is talking about day-to-day work at all (unlikely, but that's a different problem), or because everyone is siloed in their DMs.

If you've seen the chatter before you left, but it died out without you — think about why nobody else sees talking in the open as beneficial, or why are they afraid to or shy to post in the open. Do you see judgement, "well, actually", or other form of lack of support when people did talk in the open previously?

Are people asking for help?

Do you see people asking for help and advice? Sharing their in-progress work? Admitting they're struggling with a task, or admitting mistakes?

Some teams prefer a more open and direct culture than others. But in all teams where people respect and care for each other, they would support their teammates when they need help. But to share a work-in-progress, or admit a mistake, people on the team need a pretty high level of trust with each other, and with their organization leadership. Nobody would share their mistakes if they thought that doing so would affect their next performance review in a bad way.

So if you don't see any of the vulnerability and camaraderie in the team, it could be that no one needs help, or makes mistakes, or gets blocked ever (lol no, they do). However, it's much more likely that people are afraid to talk about their mistakes in the open because they don't trust that other people on the team, or you, will not use that against them.

In my experience, that kind of trust starts with leadership. Believe it or not, nobody expects you to always be right. And when you tell your team that you need help, or ask for help for help, or tell them that you made a mistake — it empowers your team to do the same. Of course, that only works if you don't punish people for making honest mistakes.

Are people debating ideas?

Do you see any new RFCs, or just discussions about how to build a feature, or what architecture would work best? Do you see respectful disagreements and debates? Strong arguments and spikes to support ideas?

RFCs, Disagreements, and debates are all critical to building a resilient, open, serene organization that sources ideas from all the talented people on the team. But it's pretty hard to get right.

Discussions take time to think and prepare through a problem at hand. Articulating engineering opinion is both a communication task (writing and presenting), and an engineering task (research, proof of concept or a spike). It's your job as a leader to balance your team's backlog in a way that gives them enough slack-time.

Disagreeing in public and taking time for research work can feel scary for the people on your team. If that work is not recognized, or if the discussions are routinely shut down and discarded because of a pressing deadline — no one will risk taking the time to articulate and post their opinion anymore. Which is pretty bad for your team's culture, and for the company as a whole, as it limits where you get new ideas. Why hire the smartest people you could find, and then shut them down?

So, if you don't see any back-and-forth on ideas on how to implement features, and close to zero feedback on pull requests overall — you should absolutely dive deeper.

Do people have a shared goal, a path forward, and a clear indication of their progress?

To stay engaged (with the company) and energized, people really need a plan that makes sense to them, an explanation of why that plan is important, a picture of what everyone else in the company is doing, and an indication of how they're doing as a team and as a company.

In the first few 1:1 conversations, ask about what goal do they think their team is working towards, and what are the next steps for them. Is there a consistent picture of the team's goals? Do people know what they're working towards, how it contributes to the company, and where they are on the path to that goal?

For people to stay engaged with the company strategy, someone has to connect them to it, and consistently relay any changes in strategy, and broadcast the current state, and the path forward.

It's your job as a leader to communicate the strategic goals, and the tactical goals to your team. If you put the right systems and communication channels in place, then your team should at the very least be informed and well-connected internally. However, your time away puts those communications systems to a serious stress test — you were not there to course correct if they didn't work.

The same goes for understanding where the company, the organization, and the team is now in their path towards the goal.

Are people cheerful?

Do you see folks recognize each other's work, and support each other?

If your team has daily written check-ins, do you see people reacting to each other's check-ins? Congratulating each other on work well done? Do people check-in at all? If you see any outliers that dropped the habit, can you figure out why?
If you have regular sync calls to check in — do people gladly share their work in progress with each other, and ask questions, or do you have to call out each team member one by one and inquire about their progress?

Engaged teams work together. The recognition and energy helps push the project forward. If you have to pull the progress out of people on your team, and the morale seems down — it's likely a combination of factors described above. Lack of clarity, lack of autonomy, lack of recognition, lack of support, or an otherwise toxic environment.

If your team culture does decay, it usually starts slow, but then snowballs. Lost trust is very difficult to rebuild, so hopefully you catch the first signs of problems in just one area before it's too late, and immediately make time and a plan to improve on it.

Automating Swift DocC with GitHub Actions

Natik Gadzhi — Fri, 16 Jun 2023 07:00:00 +0000

Some languages have nice documentation tooling: Yardoc for Ruby, Pydoc for Python, Godoc for Go. Swift has DocC, and it can export docs as a static website, too.

In this post, you'll take the Vue.js app that Swift DocC builds, host it on GitHub Pages, and write a GitHub Action to automatically rebuild and update your docs when the source code changes.

Setting up a GitHub Pages site for your documentation

On GitHub, go to your repository Settings → Pages, and set it to deploy from a branch. Select gh-pages branch, and /docs folder. If the gh-pages is not on the list of available branches — create it, and push it up.

$ git switch -c gh-pages
$ git push origin gh-pages

Note: This guide assumes that you'll be hosting your docs on github.io, and your GitHub Pages site URL will look like ${username}.github.io/${repository}.

If you'd like to deploy DocC site to a custom domain — that'll work, too, but you will need to not set --hosting-base-path.

Manually deploying the documentation to GitHub Pages

For this example, I've forked out apple/swift-package-manager. The code examples below work on that repository.

# Assuming you're in the Swift project directory (in this case, swift-package-manager itself), 
# and that your `Package.swift` already has a dependency on swift-docc-plugin.
# Runnig this will get output a `./docs` directory containing the site that we need.
$ swift package --allow-writing-to-directory ./docs \
    generate-documentation --target PackageDescription \
    --output-path ./docs \
    --disable-indexing \
    --transform-for-static-hosting \
    --hosting-base-path swift-package-manager

# Make a new gh-pages branch
$ git switch -c gh-pages
$ git add ./docs
$ git commit -m "Swift DocC site in ./docs"
$ git push origin gh-pages

It takes a few minutes to process, but when it's done, you'll get a webpage like this one.

Note: Swift DocC site is only available in a subdirectory for your particular target: /documentation/{targetName}. It would be great to have a root web page, but I don't yet know how to craft that.

So far, you've generated Swift DocC documentation, exported it as a static website, and shipped it to GitHub pages. Now let's automate it, so every time you push an update to your library, you get the updated documentation website for free.

Using a GitHub action to deploy documentation

Here's a workflow that will build DocC website, and push it to GitHub pages automatically:

name: Build Swift DocC and publish on GitHub Pages

on:
  push:
    # If you wanted to only trigger this flow on certain branches,
    # specify them here in 
    # branches: 
    # alternatively, you can trigger docs only on new tags pushed:
    # tags:
    #   - '*'

# `concurrency` specifices how this action is run. 
# Setting concurrency group makes it so that only one build process runs at a time.
concurrency:
  group: "pages"
  cancel-in-progress: false

env:
  # Build target specifies which target in your Swift Package to build documentation for.
  # To build all targets, remove this env variable, 
  # and remove --target arg in the building step below.
  BUILD_TARGET: PackageDescription

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout
      uses: actions/checkout@v3
      with:
        fetch-depth: 0

    - name: Set up Swift environment
      uses: fwal/setup-swift@v1
      with:
        swift-version: '5.8'

    # Build the DocC website using swiftPM.
    - name: Build docs with SwiftPM
      run: |
        swift package --allow-writing-to-directory ./docs \
        generate-documentation --target ${BUILD_TARGET} \
        --output-path ./docs \
        --disable-indexing \
        --transform-for-static-hosting \
        --hosting-base-path swift-package-manager

    - name: Commit and push generated documentation
      run: |
        git config --local user.email "github-actions[bot]@users.noreply.github.com"
        git config --local user.name "github-actions[bot]"
        git switch gh-pages
        git add ./docs
        git commit -a -m "Generated Swift DocC"
        git push origin gh-pages