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