Lunch & Learns

A lot of companies have a regular practice of "Lunch & Learns"—a series where engineers within the company give a presentation to their coworkers on some technical topic in which they have an interest.

I myself have given presentations at several companies where they did this, and have sat through many presentations by other engineers. Over time, I've developed a taste for what works and what doesn't.

Set the Stage

Start with the basics: Who are you? What do you work on in the company? Why is this topic important to you?

I've watched too many of these where someone starts the presentation by screen-sharing what seems like a random code file in Visual Studio (or their code editor of choice), and just starts talking in minute detail about lines of code in the file. No context at all for: what am I looking at, what is this, why is this significant, what is this application, what does this application do, why would I care, what am I supposed to do with this information, etc.

Go Beyond Generic Content

I've sat through too many "Introduction to X" presentations. They always have generic names like "React.js" or "Test-Driven Development". Now, there's nothing wrong with introductory content, but here's the thing: the audience knows how to use YouTube. If they want a generic introduction on some technical topic, there are undoubtedly free videos available that are more authoritative and higher quality.

If the content of the lunch & learn is completely generic in a way that it could be given to any group at any company without context, then there's really no good reason to be gathering a captive audience at one particular company to watch it.

Take advantage of the unique experience you have with the topic as it pertains to the projects and domain of the internal audience. Make the generic specific.

Make It Practical

What value is your audience going to get out of this presentation? Here are some lunch & learns I like to see:

• This Is How We Used X to Do Y in Application Z
• How to Replace X in Your Project with Y
• Postmortems / Lessons Learned from Project X

One of the best tech leads I've ever worked with once gave me some advice about technical presentations that I've never forgotten. He encouraged me to think about "presentation to Production". It's one thing to give an interesting presentation, or pick an interesting topic, but the next level is to think about "How are we going to put this technique/language/framework/practice into Production?"

Include the Thing

I literally wrote a blog post a couple years ago called Include the Thing about effective written communication for engineers. And it's advice that is totally applicable to presentations.

Look, no one wants to watch a presentation where someone is showing a PowerPoint deck and simply reading the slides back to you. But I think some people, especially engineers, go too far in the other direction and eschew any kind of written outline material for a lunch & learn.

It's great to "show the code", but it's next level to leave a written artifact (PowerPoint deck, Wiki page, etc.) with links to the specific internal code repositories (GitLab, Bitbucket, whatever) and individual files that you were looking at in your local code editor during your screen-share.

For lunch & learns at my current company, we do the trifecta: 1) wiki page including… 2) embedded PowerPoint deck and… 3) embedded screencast video of the presentation. Anyone coming along later who couldn't attend the lunch & learn live, or anyone who wants to refer back to the content has all the context they need.

New People Write the Best Documentation

Have you ever heard that the best way to learn a subject is to teach it?

I've had the experience several times when I've joined a new team and started ramping up, that their documentation is out of date and skips over important information.

We know there's always that awkward transitional phase when a new engineer joins a team that's existed for a while, because they're not immediately ready to take on "real work", even if they're an experienced engineer in general. 

This is a perfect opportunity to improve the documentation! In fact, I think a great first assignment for an engineer new to a team is to update the onboarding documentation. They'll see exactly what's missing as they try to follow along, in a way that veterans on the team never will.

When experienced folks are tasked with writing documentation, they don't need the documentation, so they will tend to hand-wave and make leaps in explaining things because they're not truly starting from scratch like a new person is.

Documentation written with a fresh perspective is so helpful, and of course, living documents are best. Establish a virtuous cycle where each new person leaves the docs a little better than they found them.

Include the Thing

I suppose you could file this post in my series of remote work posts, but it's really just about effective written communication in a team setting.

Here are some tips that I would summarize simply as: Include the Thing!™

Links

The humble hyperlink. Oh, how you simplify communication. Almost everything we do now is link-able.

• You're writing a backlog item description that mentions work previously done. Include a link to the canonical backlog item that describes the previous work!
• Someone has asked you a question in chat that you remember being answered by an article on the team's internal wiki. Hunt down the wiki article, chat them an answer that summarizes the relevant section of the article, and include a link to the article if they want a fuller answer! 
• The build is broken. Crap! When you ask your teammates about this, include a link to the build log in GitLab that shows the error message.

Screenshots

A picture truly is worth a thousand words. There is almost always a good reason to include a screenshot. Reach for the PrtScn key as often as you reach for your glass of water.

• Hey, I'm getting a JavaScript error when I click on that button. Include a screenshot of your browser that includes the button in question with your Chrome console open and showing the exact error you're talking about! Bonus points if you draw a circle around the button and the error text in the console. Bonus points if you capture in your screenshot the address bar showing the complete URL of the page in question.
• Hey, I was looking at the config file and I'm wondering if that connection string is wrong? Include a screenshot of the config open in Visual Studio with a circle drawn around the line in question. Bonus points if you include several lines above and below so that the location within the file is obvious. Bonus points if you have line numbers turned on in your editor and you've captured the line numbers within the screenshot. Bonus points if you've captured the tab within the screenshot that shows the complete file path to the config file, or at least the file name.
• Hey, I'm creating a JIRA ticket and I couldn't figure out which Project to pick. Include a screenshot of the complete new ticket form in JIRA where you've already filled out all the fields that you already know. Bonus points if you drop down the Project drop-down before taking the screenshot so the complete list of Project options is visible.

Quotes

Including a relevant portion of a previous communication in your current communication provides focus and context.

• You're emailing a co-worker on a different team that you don't talk to that often about a problem they helped you with several months ago. Instead of composing a new email from scratch, dig up the email thread from when they helped you previously and email them this time as a reply to the previous thread so that the context of your previous conversation is appended to the email!
• You're writing an article for your team wiki and there's a relevant article on MDN you want to link to. Copy and paste the relevant section of the MDN article as a blockquote within your Markdown!
• You're replying to a question a teammate asked a few hours ago in your team chat, but there have been many unrelated messages in the chat since then. Use the feature your chat app has for establishing a context for your reply! Some apps have a quote feature that includes the other person's message on top of yours. Some like Slack allow you to reply as a thread to the original message.

Why?

Whether you're using links, screenshots, quotes or something else, the goal is to:

Anticipate questions

What's the next thing the person I'm communicating with is going to want to know after they read what I've written? Can I just include that information now?

Ruthlessly eliminate ambiguity

What information could I include now that could point more directly at the subject? How can I be more specific? What is potentially vague about what I'm communicating?

Reset the context

How can I depend less on this person's memory to understand what I'm communicating? Is there a chance they've forgotten our previous communication? How can I establish a context for this communication?

Include the Thing!™

Showing Up for Remote Work

Remote work is awesome. I've been doing it full time for over 5 years now, and I've learned the importance of "showing up" as a remote worker.

It's really easy to feel disconnected from people when you aren't in the same physical space. I've picked up a few habits that have helped me stay visible as a remote engineer.

Show Your Face

People are instantly humanized again when you see their faces. I've found myself assuming things about someone's personality and attitude when I've only communicated with them via text.

Who would you rather leave a comment on your pull request?

or

By default the various services that you use at work to collaborate with people are going to give you a lifeless avatar. Do the bare minimum and upload a picture of yourself to your profile on each one.

The same goes for Zoom meetings. Every laptop these days comes with a webcam, or you can buy a cheap USB version and clip it to the top of your monitor. Even if your hair is messy and your home office is drab looking, just turn on your webcam. Don't be this guy:

Speak Up

Simply hearing someone's voice is a powerful thing when you're not in the same physical space. It doesn't take much to just say "Good morning." at the beginning of a Zoom call or "Thanks, see ya." at the end of a call. 

When I'm attending meetings remotely, I try to speak more than I probably would if everyone were in the same room. Even if I don't have anything particularly original or earth-shattering to contribute, it doesn't hurt to say "Yeah, that makes sense" or "I agree". Your silent nods aren't going to be noticed in a Zoom call with ten people.

Show Your Work

I try to take advantage of the various activity feeds that surround my work as a software engineer.

For example:

• Instead of coding for days on a backlog item and then making one big commit-push to the team's Git repository, break your work into smaller logical chunks that you can push daily
• If you did some research as part of a backlog item that won't be captured as code in the repository, write up an article in the team wiki summarizing your findings and link to it from the backlog item or post a link in the team chat
• Instead of the briefest possible comment in the morning standup like "Still working on item #4567", give a few sentences description of the specific progress you made on that item
• Tag specific people in the comments on backlog items, pull requests, etc. when you've done some work that would be of interest to them

Acknowledge Communications

It's easy to feel like you're writing into a black hole when working remote. Let people know you're paying attention.

When someone writes a message in the team chat that helped you, throw a thumbs-up on it or tag them in a reply to say thanks. Same goes for nice or constructive comments on wiki articles you wrote or pull requests you submitted.

With Great Power Comes Great Responsibility

Remote work arrangements are a great benefit for engineers, and they require a great deal of trust between employer and employee to work. Since I'm not showing up in person, I make a conscious effort to show up in other ways.

PowerShell Tip: Pipe to the Windows Clipboard

Through this blog post, I discovered the wonderful clip, which allows you to pipe to the clipboard from PowerShell (or cmd).

The IT department at my company has a weird scheme that they like to use for assigning computer names, so I find myself running a PowerShell command like this several times a week when I need to summon my cryptic computer name:

$Env:COMPUTERNAME | clip

PowerShell Tip: Get Synopses for All Built-in Cmdlets

I've been messing around with PowerShell quite a bit lately.  Here's a little one-liner I cooked up that's helping me as I continue to familiarize myself with PowerShell's built-in cmdlets:

gcm | get-help | ft name, synopsis -auto

And here's what the results look like: