Forem: Alyss 💜

Unofficial guide to Slack literacy: communication in a remote-first world

Alyss 💜 — Tue, 18 Jan 2022 19:19:40 +0000

Before landing my first job in tech, I’d already been well acquainted with IRC, ventrilo, and message boards. With a career came Campfire (Basecamp) and then Slack launched in August 2013. Slack, for the purposes of this post, is used as a proxy for asynchronous chat platforms/tooling. Such software has become ubiquitous to the daily toil for knowledge workers and expands into professional, personal, and hobby communities.

Basic rules of etiquette

Unless you’ve formally discussed the use of @channel or @here on your team and there’s a shared understanding of when to use it, err on the side of never using it. I’ve personally found this notification used more frequently among sales teams or within groups where most users do not have a desktop app installed and access through a browser instead.
When sending a direct or private message, send a single message with your request. (e.g. Hello! Can you share any updates on the Apollo project?) There are individuals who may prefer an opening salutation or some kind of friendly watercooler banter but the point of async communication is you don’t have to sit around waiting to have a conversation to get a question answered. If you’re working across time zones, you can also consider scheduling a message to send.
Set your own boundaries. Slack has a notification schedule feature and Do Not Disturb (when you may want to focus or go on vacation).
Finally: Set a profile photo, pronouns, and name pronunciation*.

*Enterprise slack plans have more configurable profile fields, like name pronunciation. This may not be available in your slack experience.

Intermediate skills

Mentions

If an individual isn’t in the channel or private message, using their tag or handle will not notify them. For a channel in slack, a message will appear asking if you’d like to invite or notify them (or do nothing).
@ mentions can be disruptive. If you’d like to mention a person without notifying them, placing their name or handle in backtick/code blocks (e.g. @preciselyalyss). You can do this when you aren’t sure if they are in a channel but still want to reduce noise/distractions.
If you are interacting via a private message, you don’t need to tag/@ mention participants. They will be notified by default. In a private group DM, you can further configure your notification settings.

Channels

Read descriptions and pinned messages for a channel if you aren’t sure how to interact. Rules of engagement may be documented or the best way to engage with a particular team.
Organize slack channels with the sections feature

Reactji + Emoji

Reactji are highly cultural. We have over 10k custom slack emoji at GitHub. Sometimes these gain more traction, like Atlassian popularized chompy when HipChat shipped with the character in the default emoji set. Chompy was used when posting that lunch was available.

Most platforms allow you to configure a default skin tone of the core emoji set. Please think about this. Even leaving the default to yellow should be a deliberate choice, in my opinion. More reading here and here.

Threads

There are no universally agreed rules that I’ve observed on Threads yet. They are still fairly new feature to several platforms. It can help with multi-threaded conversations but does change the notification location or reduce visibility in some cases.

Advanced

Writing styles

Chat is a highly informal medium and written communication can be fraught with opportunities to miscommunicate and misunderstand. It is possible to reduce the risks but never fully mitigate them. If you're unsure of the tone something was written in, ask.

Some rules I follow:

If there’s a context-loaded word, like DevOps, I try to define what usage I’m intending when discussing in chat.
Incorporating non-violent communication.
Explicit requests vs implied. “Can you do x?” instead of “X needs to get done”

Consider cultural-specific communication

Do I have teammates that wouldn’t understand this reference?
Is this a necessary reference if it does exclude people who don’t understand and should I explain it?
Is there potentially ambiguous or inflammatory meaning? (e.g. Gifs or images referencing Winnie the Pooh when speaking with China-based colleagues could have an unintended impact)

If you’re interested in further improving your remote-first skills, You Got This is a community event series with even more educational content to dive into.

Install Groovy with ZSH (plus automation in Jira & Confluence)

Alyss 💜 — Wed, 22 Aug 2018 15:48:18 +0000

Full disclosure: I work for Atlassian. As a result, I spend a great deal of time creating, updating, and reading Confluence pages. While Confluence server and cloud both have APIs which can be used to programmatically update/create pages, Adaptavist created an app called ScriptRunner which makes this easier with built-in scripts and pre-written logic. My end-goal is to automate some common, reoccuring tasks either by checking a Jira issue for updates or another confluence page. Most Atlassian applications are written in Java and ScriptRunner uses a flavor of Java called Groovy.

Step 1: install Groovy on OS X

For Homebrew users:

brew install groovy

For MacPorts users:

sudo port install groovy

Step 2: Set Groovy_home environment variable

You are welcome to do this entirely in zsh, but I manually added it to my ~/.zshrc file. Another note is I have Sublime set up to launch from the command line. If you prefer vim, emacs, or another text editor, you will need to substitute references to subl.

subl ~/.zshrc

Within ~/.zshrc, I'm adding the following variable export and comment:

# Add Groovy Home path
export GROOVY_HOME="$(/usr/local/opt/groovy/libexec)"

Save this file, then you can close it once you're done.

Step 3: Run a test to check your Groovy install

mkdir groovy-test && cd groovy-test
subl hello.groovy

Now, add a test script to the empty file you just created:

//hello.groovy
println "hello, world"
for (arg in this.args ) {
    println "Argument:" + arg;
}
// this is a comment
/* a block comment, commenting out an alternative to above:
this.args.each{ arg -> println "hello, ${arg}"}
*/

Save this file, then you can close it once you're done.

Run it with the following:

groovy hello.groovy MyName yourName HisName

Step 4: Start using Groovy to automate tasks in Jira or Confluence

As I mentioned before, Adaptavist offers some built-in scripts but I find my needs are more complex. There are some good examples floating around the web to help get started.

3 Secrets to Improve your Travel Experience

Alyss 💜 — Tue, 17 Jul 2018 22:19:59 +0000

In more than two decades of travel, I've packed hundreds of times and flown hundreds of thousands of miles. With all those WiFi-less flights, I have had time to iterate on my travel strategy (if you can call haphazardly planning a strategy).

If you are looking for ways to improve your airplane travel experience, I've included my favorite tips to foist on unsuspecting friends and coworkers like how to get more out of your suitcase real estate, avoiding a rat's nest of electronic cables, and how to look fresh-faced (and hydrated) after a long flight.

Pack like you're going to have to do it again

Packing is a necessary evil of travel. Whether you pack two hours before your flight or two days before with a checklist, you can improve your experience with a couple of additions to your travel kit.

Packing cubes in practice

The best packing improvements I've experienced have had little to do with the bag itself. If you take nothing else away from this post, get yourself some packing cubes. My first purchase was for The Wirecutter's top recommendation, Eagle Creek Pack-It cube set. After my significant other commandeered those, I upgraded to Eagle Creek's Pack-It Specter Compression cube set.Most of my outfits end up in the full-sized cube. I find the half-cube works great for underwear, socks, and bras. I have rarely found the quarter-cube useful, so I leave it out or use it for toiletries.

Packing cubes really shine once you start unpacking at your hotel. Finding the shirt you want no longer requires unpacking half your suitcase. Repacking is a breeze since you’re placing the cubes back into your suitcase as opposed to refolding and figuring out what tetris-solution you came up with originally.

Packing cubes aren't just for your suitcase either. I put one in my carry-on with a spare change of clothes and a hoodie. If your bag is lost or the plane is freezing, then you have everything you need for a day.

"Please stow all large electronic devices..."

How many electronic devices are in your carry-on? Maybe a Switch (plus games), a kindle, a laptop, and bluetooth headphones. If your experience is anything like mine, you left your kindle on scanning for wifi or entertained yourself by reading reddit on your phone for the last hour before your flight boards. Now that you're facing a 3+ hour plane ride without wifi and dead or dying devices, it's time to untangle the mass of cables at the bottom of your backpack.

Forget. That. Start by getting yourself a cord organizer. It is way easier to take in and out of your carry-on. While you're at it, get a backup battery. Most USB ports on planes output 0.5 amps, but many phones use some form of quick charge and require 2 amps or more. Besides, you don't know where that USB has been.

If you're reading this, drink some water

Doesn't matter if it's a one-hour puddle hop or an 18-hour trans-pacific flight, planes dehydrate everyone. With climate control, the relative humidity on planes can get as low as 4%. The Boeing 787 and Airbus A350 can achieve 10-15% (or more). By exchanging some of the metal components with carbon fiber, they can support greater humidity without reducing the life of the plane due to corrosion. All that said, 10-15% relative humidity is still drier than the Sahara.

Reduce & reuse

Walk into any airport in the US, and you're bound to see a 20oz bottle of water for $2.50 or more. If you're passing through Chicago's O'Hare, it is closer to $3.40. Don't worry, you won't be shelling out for those. For $9-15, you can get a collapsible water bottle. Take it through security, pack it in your bag, or clip it on to a strap.

An increasing number of airports have bottle-filling stations. Swing by one before boarding and try to avoid caffeine/alcohol on the flight. For longer trips, you might want a second water bottle, or you can make friends with the flight attendants.

Transepidermal water loss or "why you need a plane skincare routine."

Remember the paltry humidity levels on planes? Well, your skin hates it. Transepidermal water loss (TEWL) is when water passes from the dermis through the epidermis and evaporates from the skin's surface. Low humidity conditions increase the rate that our skin loses moisture through TEWL. Basically, you're going to come off that plane looking just as jet-lagged as you feel.

The best way to combat this is with a combination of humectants (hydrator) and occlusives (moisture seal). I won't dive into the nitty-gritty of skincare science, but here are a couple recommendations to take in your carry-on for your next flight:

Hydrators

The Ordinary's Natural Moisturizing Factors + HA, $5.80 + shipping

Moisture seals

Vaseline
Shea butter

Combination

Etude House Honey Cera Cream, $24 + shipping
Cerave Healing Ointment w/ Hyaluronic Acid and Ceramides, $8.50 + shipping

Happier traveling!

Trekking through airports, past security, and into a new city is exhilarating and exhausting. A few mindful inclusions can improve the quality of the experience. For your next vacation, family reunion, or business trip, try out my recommendations then sit back and enjoy.

Explain BigInt Like I'm Five

Alyss 💜 — Fri, 25 May 2018 18:18:18 +0000

Nevertheless, Alyss 💜 Coded

Alyss 💜 — Thu, 08 Mar 2018 05:09:53 +0000

Stress Way Less: Building Psychological Safety at Work

Alyss 💜 — Wed, 24 Jan 2018 15:16:03 +0000

What does psychological safety mean?

My own familiarity with the phrase "psychological safety" started when I read Smarter Better Faster: The Secrets To Being Productive in Life and Business by Charles Duhigg. He references research that Google started on a quest to create a more productive team. The increased discussion of psychological safety illustrates the community's recognition that there is something wrong and there is desire to elicit change. But, what does that make "psychological safety" other than our latest buzz phrase?

Psychological safety is defined as the combination of trust between coworkers, and an environment in which that trust can be acted upon.

In the healthcare and aviation industries, this is often referred to as "just culture". The U.S. Federal Aviation Administration defines this as, "A culture…that has both an expectation of, and an appreciation for, self-disclosure of errors. A 'just culture' allows for due consideration of honest mistakes, especially in a complex system like the National Airspace System (NAS). But even unintentional errors can have a serious adverse impact on safety, and so we must ensure that the underlying safety concern is fixed in all cases."

Thought exercise: what would a hospital visit look like if patient charts were mixed up? Now, think about what would happen if patient charts were mixed up but a hospital employee wasn't willing to admit what happened? It is a scary thought and tech is touching more than just healthcare these days.

The thought experiment encourages you to consider the worst case scenario which frames the benefits psychological safety can convey. The tech industry is in desperate need of something to disturb the status quo of unhealthy work environments. Productivity has been in a slump globally and fostering psychological safety could create an environment where innovation can further blossom. Psychological safety is foundational to improve workplace relationships and mental health.

Start with building trust

Assumptions in communication can provide a plethora of roadblocks to finding common ground. Before jumping into how we go about building trust, I'd like to set a shared vocabulary (from Emotional Intelligence 2.0):

Self-awareness: the ability to accurately perceive your own emotions in the moment and understand your tendencies across situations.
Self-management: the ability to use your awareness of your emotions to stay flexible and direct your behavior positively.
Social awareness: the ability to accurately pick up on emotions in other people and understand what is really going on with them.
Relationship management: the application of social awareness, self-awareness, and self-management to manage interactions successfully.

Establishing trust among peers

Can you depend on your teammates? Trust falls at corporate retreats don't count. Do you leave a meeting and think, "I'm going to have to follow up with them to make sure that gets done"? Or is there a teammate that dazzles you with their ability to respond to every email they get? The former doesn't feel dependable and the latter does. Understanding where your loss of trust comes from is one part self-awareness and one part social awareness. This can breed resentment if you feel you have to do extra work just to make sure someone else does their job.

When you no longer feel you can trust your coworkers, productivity and your ability to collaborate breaks down. How can this cycle be disrupted? At an individual level, you can:

Keep your word — and if you can't, say it sooner rather than later. Your teammates can help you out if you sound the signal early that you need help completing the work, whatever the reason may be. Knowing earlier will also help them fit this into their schedule in a more optimal manner than if they'd found out at the last minute about this extra task.
Tell the truth — this doesn't mean "tough love". Your perspective of events is not the universal truth and creating a culture of safety requires recognizing that. Truth must be measured by the words we use and not just the message we intend to convey as it may have an impact to the contrary.
Be transparent — sometimes two different people have two different end goals in mind, especially in collaboration or when it comes to corporate alignment. Be up front. Your teammates can't read your mind and they certainly can't help you reach that goal if you don't tell them what it is.
Be willing — to help, to mentor, to listen, et al. Don't do it because of what you can get out of the interaction; do it because that makes someone's job easier or their day better.

Setting clear expectations

Pop quiz! If you had to write your job description in 10 minutes, could you do it? You can't reference the job description you were hired under and you can't ask for input. Would the end product of this exercise match the job description you were hired under? Chances are this is a challenge and the output wouldn't match.

If you can't clearly define what your job description and responsibilities are, chances are that your coworkers can't either. Teammates and coworkers may have pretty good ideas, but this sets up teams and organizations for assumptions based on non-uniform expectations. How can you hope to build trust based on expectations that aren't communicated? People managers should work with their direct reports to:

Communicate & enable desired behaviors

Don't neglect emotional intelligence in favor of performance metrics. Both are important to the success of your organization and/or team. Complement this by tailoring employee assessments to individual behavior. A quiet introvert won't necessarily respond or improve when told to assert themselves in meetings. If you are struggling with the goals your manager sets, discuss it with them.

Understand role accountability and discuss expectations

It is possible for two or more people to have one or the same role, depending on what they do. Discuss what work you're accountable for and expected to complete. Clear expectations will help you have consistent communication and manage work relationships through addressing assumptionsyour peers may form. It will also help set a shared vocabulary you can use with your manager to discuss progress or difficulties in your role.

Set realistic goals and reasses

Goals should be guided by your responsibilities. If you (or your employee) aren't meeting goals, talk about it. Not everyone talks about when they feel overwhelmed or when there are personal matters outside of work that may impact their performance. Check in with your manager and your teammates. It is great practice for improving self-awareness.

Be accessible

You can't be everywhere at once and, if you're managing people, you may have more than one report. When peers have feedback about your employee or questions about their role, make time to listen. You can support your employee by addressing these questions, setting appropriate expectations about their role, or listening to praise (or concerns) their peers may have.

It boils down to building social awareness and helping your employees manage their relationships with teammates. If you feel this list is a little shallow, I would agree, but I don't feel like I can do it justice in this post. Some great tools exist to support accomplishing these goals such as the RA(S)CI model and SMART(E) goals.

The story of company culture

Clarity is more than a well-written job description; Gallup has found that it also depends on employees understanding how their work aligns with the organization's mission and business goals.

Another thought exercise: can you give your company's 30 second elevator pitch? Toyota, as an example, focuses on vehicle safety as their ultimate goal. That sounds pretty compelling to a consumer: you may prefer cars that help me stay safe on the road. As an employee, you could consider that the marketing we are doing should always support that ultimate goal. It can have a different primary message, but that "Safety" message should be present. As an engineer, you would know your KPIs(key performance indicators) will focus predominantly on the safety of what you design and why your performance is measured that way.

What I have learned is that this is also how the best products and companies are built. Made to Stick discusses it in-depth. When the modus operandi is clear from the Executive level to every other corner of the company, you get Southwest Airlines and the success the Palm Pilot saw when PDAs just weren't working for consumers.

Start telling a strategic narrative. Company leaders should support this narrative with great stories of what is happening within the organization and not just their own team. Talk about successes and how teams within the organization came together to accomplish the bigger picture. Employees can anchor against this and better understand the value of their work and the work of their teammates.

This article was originally posted on Medium, but has since been revised.

Slate, Swagger, and Silos - A Documentation Rebuild Story

Alyss 💜 — Tue, 28 Nov 2017 19:40:22 +0000

In 2016, I migrated the API and front-end documentation of an e-commerce platform from Contentful to Slate as my first solo (and major) ruby project. At the time it was migrated, there were probably around 20 API endpoints documented and none of which had a swagger spec. Not only were there APIs, but there were TWO front-end frameworks that needed to be contained within the same site. My intent of this post is to discuss the specific problems this project posed, how they were tackled, and some constraints. If you are investigating static sites or Slate as a documentation solution, I hope you find value in my experiences.

Problems

As with any product, I had a wishlist of improvements. But it is easy for your eyes to be bigger than your stomach.

Information architecture was atrocious. Users tended to bookmark pages more than suffer the structure.
API resource pages were split and not linked to each other.
No search, making the above problems even worse.
Code samples existed only in SDKs and clients hosted on github.
Basic getting started information was buried
Load time was meh.
Updating content required a user seat.
No SAML/SSO which mattered for a company that managed off- and on-boarding through LDAP.

That list doesn't seem so bad, but with the curse of knowledge, I knew there was more to each than meets the eye. Having the luxury of experiencing Twilio's API documentation, it was tough knowing the high standard it would be compared to.

Will the code samples have syntax highlighting?
Is the search site wide or only in-page content?
How will access be handled?
How do I manage the IA (information architecture)? Can it be easily updated?
What is the learning curve for new admins?

Solutions feat. Slate

Out of the box, Slate has only a single page. The index page is typically used by other Slate forks as a landing page (for multiple endpoints) or as a feet-first introduction to the API with a header acting as the introduction. Given the nature of API and front-end documentation, I needed to use this as a landing page.

Information Architecture

Since Slate is based on middleman, the directory structure felt pretty straight forward. I could create subdirectories such as /api, create a new index.html within that, and boom: localhost:4567/api/. The main issues I ran into when working with this were three-fold:

The information architecture could easily become convoluted from a user or developer side. With two major API versions, I needed /api/v2/ and /api/v3/. On top of that, there are 25 resources or more (not including subresources) to cover in the documentation. I had to decide which was the lesser of two evils: a very long page (but one with search and side-nav) or many subdirectories and landing pages.
[Lesson learned way later] Pages with a lot of content can have some interesting issues in Slate. Specifically, using the navigation, some content wouldn't show up until you refreshed but the page had fully loaded. The way I had Slate deployed was via github pages, so the site was pre-built with static html. There was no JS or back-end nonsense that should have prevented rendering. I never figured this one out.
If I wanted multiple pages within the same subdirectory, it was relatively easy to name the file something like api-endpoint.html instead of index.html. The issue I had with this was relatively minor, but the final html rendering between various gems didn't like this in a few places (tables). It also hampered the search effectiveness without a federated search like Algolia.

Speed

There is no room to complain about speed with Slate. It is self-contained and only as bloated as you end up making it. At the time that I'm writing this, the dev branch for Slate has a way to pre-render the side navigation. During the migration work, it primarily used javascript. In testing the page speeds using Chrome Developer Tools and a variety of site speed tools, I noticed one page was an outlier. After wrangling further with DevTools, I was able to get a javascript profile of the page load which helped me identify the javascript functions that were taking the longest.

In my attempt to have every endpoint on the same page by version (/api/v2/), the js generating the side-nav was taking ages. It totaled about 1s+ on desktop. I presented a bit on using Nokogiri for pre-rendering the table of contents as I had worked on it asynchronous from Lord (Slate's creator). After implementing the Nokogiri pre-rendering, load times were 👌. By changing the ToC (table of contents) build function from client-side to sorta-server-side, the greatest damage was mitigated.

Search

As a static site, there was no full-site search but Slate did have in-page search with lunr.js. My only change was to the highlighting feature. I noticed with large pages, there was a significant feeling of lag after a single character had been typed. Increasing this to three characters was more likely to be relevant to the user without impacting their experience.

Since leaving the company where I implemented this, they will also be incorporating Algolia as a federated search across multiple sites. It is a great solution and would've worked well with Slate using DocSearch.

Swagger, meet Slate

During the development process, the company I was working for was in the midst of building a new major API version. This API version featured Swagger specs for each endpoint (and I was overjoyed for that). This presented an interesting project.

In the past, every API update was documented by hand. I had done this by reading PHP and others had done this by talking to the engineers or digging through Jira tickets and pull requests. Swagger offered a consistent format, an existing editor that provided documentation and examples, and had an ecosystem to support it. With primary contributions from a product manager that loves code, we ended up using Widdershins to consume the swagger file and output Slate-compatible markdown. Widdershins also helped create code samples using doT.js for templating.

If you're working with Slate or evaluating it and have questions, feel free to ping me regarding them. 🕺

Thank you to Elana and Nick for helping with final editing on this post.

Explain Artifacts (Deployment) Like I'm Five

Alyss 💜 — Thu, 02 Nov 2017 18:11:42 +0000