When it comes to organizing source code repositories, there are broad similarities — source code in src/, tests in test/ — but no universal standards. Recently I was thinking about this and wondered “What about UNIX?”

Most Linux distributions follow the Filesystem Hierarchy Standard to some extent. The directory names are short and familiar. The structure was even organized around how files change.

What would this look like applied to a project repository? Starting with the usual src/, test/, and doc/ directories, we could add UNIX-like paths:

• bin/ for executable commands (binaries and scripts)
• lib/ for shared libraries, such as shared functions for scripts
• share/ for architecture-independent shared data, such as images
• etc/ for local configuration
• var/ for anything that changes
  • var/lib/ for data that persists over multiple executions
  • var/run/ for runtime data like PID files
  • var/log/ for log files
  • var/tmp/ for temporary files and cache
• opt/ for self-contained directory hierarchies, such as Git submodules or embedded dependencies

This structure has some interesting and potentially useful consequences for how repositories are structured. Everything except var/ should be tracked by version control, and everything in var/ should be excluded from version control.

Since var/ is the only non-version-controlled directory, it is effectively the only “writable” destination for compilation. This means the files in bin/ and lib/ might be merely symlinks or scripts that point to generated files in var/lib/.

In a cloud or container environment, var/ or its subdirectories could be mounted from a separate filesystem.

The etc/ directory is tricky since a project may require temporary configuration files during development that should not be checked in. My thinking is that etc/ should be restricted to things that are normally “checked in” like default configuration values. Local-only config should be under var/. It’s not unheard of for *nix systems to have a var/etc/, so that could work.

Of course, there is no universal standard for *nix filesystems, and no universal agreement on how to implement the standards we have. But as with a lot of things in software, you could do worse than to follow in the footsteps of UNIX.

Recently, my personal consulting business led me into a nest of Python, a language I had somehow managed to avoid for the past 15 years. I found, somewhat to my surprise, that I rather liked it. I wouldn’t call it great, but it’s easy to pick up and gets the job done. Packaging and namespacing is a mess, but no worse than any other language of its era.

I found that Python has just enough functional paradigms to keep me from tossing it out the window. Nothing compared to Clojure, of course, but enough.

Then I hit a stumbling block. I was writing an API which needed to receive a collection of things. I needed to use the first item of the collection for some initial setup, then iterate over the whole collection. It seemed straightforward enough:

def do_work(things):
    first_thing = things[0]
    print("Initial setup with %r" % first_thing)
    for thing in things:
        print("Doing something useful with %r" % thing)

I tested it with a list of things and it worked fine.

do_work([1, 2, 3])

Initial setup with 1
Doing something useful with 1
Doing something useful with 2
Doing something useful with 3

Then, in another piece of code, I decided to push my growing confidence in Python and try one of these new-fangled generators I’ve heard so much about:

def generate(n):
    for i in range(n):
        yield "generated value %d" % i

I eagerly tested it and …

do_work(generate(3))
TypeError: 'generator' object is not subscriptable

Oh, poo.

OK, you caught me, I made the cardinal mistake when learning a new language: treating it like another language I already knew. In this case, I was trying to use a Python generator the same way I would use a Clojure sequence.

Clojure sequences are immutable and automatically cache generated values as long as they are reachable. In Clojure, I would have written something like this:

(defn do-work [things]
  (let [first-thing (first things)]
    (println "Initial setup with" first-thing)
    (doseq [thing things]
      (println "Doing something useful with" thing))))

Immutability makes things simpler: just because I did (first things) doesn’t change the value of things.

Python generators are more like suspended computations; once they yield a value there’s no way to get it back. So Python will not let me “subscript” a generator — as in things[0] — because a generator cannot fulfill the expected behavior of a list, i.e., that the elements stay put after you look at them.

I understood the Python error message pretty quickly. Then I spent several minutes banging around the internet looking for a Python equivalent to Clojure’s immutable sequences. There probably is such a beast, but I didn’t find it.

There are plenty of workarounds, of course, the easiest being to coerce the generator into a list:

do_work(list(generate(3)))

Initial setup with 'generated value 0'
Doing something useful with 'generated value 0'
Doing something useful with 'generated value 1'
Doing something useful with 'generated value 2'

I could have stopped there and been just fine. But that list() stuck in my Clojurist’s craw. Forcing the entire generator to be realized in memory just so I could hang on to the first element felt wasteful. Who knows, maybe it would even break one day when handed a generator that produces thousands of items.

After a bit of tinkering, I came up with:

from itertools import chain

def do_work(things):
    iterator = iter(things)
    first_thing = next(iterator)
    iterator = chain([first_thing], iterator)

    print("Initial setup with %r" % first_thing)
    for thing in iterator:
        print("Doing something useful with %r" % thing)

It’s not what I would call elegant. But it works, and it’s flexible: things can be any iterable type, including a generator or a regular list.

(For the Clojurists in the room, chain() is analagous to Clojure’s concat: it creates a new iterator out of two iterable things.)

After I finished the requisite rant about silly languages that don’t embrace immutable values as a pervasive default, I got to thinking: Clojure’s immutable sequences are elegant and powerful, but their design has some subtle consequences that regularly trip people up.

Almost everyone learning Clojure has stumbled over the holding onto the head bug, which is a direct consequence of sequence caching. Keep at it long enough and you will eventually hit the stacked sequences problem. These bugs may not show up during development; they only come back to bite you when they hit a sufficiently large sequence in production.

Furthermore, it takes knowledge of what’s going on behind the scenes — how Clojure sequences actually work, as opposed to the surface API — to understand the problem. Recognizing memory leaks before they cause problems is usually a matter of experience and pattern-recognition. For someone who just grabbed a syntax cheat-sheet and skimmed the standard library docs, there’s a good chance of writing that bug but not much chance of knowing how to fix it.

By contrast, Python’s generators and iterators are a little more … mechanical. You can see how things work, because most of the parts are exposed for you to see. While I’m sure there are ways to write memory leaks in Python, I’m guessing iterators are not a common source.

This is not to make a point about one approach being better than the other. I’m not going to rehash worse is better for the nth time, nor the law of leaky abstractions. I merely note that there are trade-offs either way. A more “elegant” abstraction can produce shorter, more expressive programs, at the cost of hidden complexity. Exposed mechanisms are easier to observe, but force you to spend attention on mechanical details.

“What do you mean, How to join a meeting’?! You click a button, doofus!”

Yes, dear friends, and that is exactly the problem. If you’re not accustomed to remote work, you may not dwell much on the mechanical processes of remote interaction. It’s just always awkward, isn’t it? Every meeting starts with several minutes of fumbling with microphones and cameras and “Can you hear me now?” With each new person who arrives, the whole dance starts over again.

But what if I told you it doesn’t have to be like this? That it is, in fact, possible to have a remote meeting start on time, with everyone present and audible and ready to work? All it takes is a little preparation and a few organizational adjustments.

Take a Break

First and foremost, don’t schedule meetings back-to-back. Even the most plugged-in manager needs time to breath, stretch, use the bathroom, drink some water, and check their email. Ten minutes is not enough, especially since most meetings run ten minutes late anyway. A half-hour break is the minimum you can realistically get away with. An hour is better.

“But with half-hour breaks in between, how will I have time for six meetings per day?” You won’t. That’s the point. No one can sustain that many context-switches and still make meaningful contributions. With half as many meetings, and time to reset and gather your thoughts in between, you will be twice as productive.

Start Early

Secondly, start meetings early. That doesn’t mean the work of the meeting should start before its scheduled time, but that people should begin interacting in a virtual space before the scheduled start time.

My pre-meeting ritual looks something like this:

At T-minus-10 minutes, I get a notification from my calendar that the meeting is coming. I take a few minutes to wrap up whatever I’m working on and make a note of what I was planning to do next, so I can pick up where I left off.

Next, I check that my computer is ready for a meeting: headset plugged in, wired network connection in place, camera cover open. I turn on more lights so the camera image is clear. If you have a Zoom shirt, this is the time to put it on as well.

At T-minus-5 minutes, I join the video call. This means I have plenty of time to open the correct app, find the meeting link or access code, and restart that app or even my whole computer as many times as needed until it works. If the app offers a way to do it, I will test that my headset is working correctly.

Once I know I can connect to the meeting, I leave my desk. That’s right, I walk away and leave the camera pointed at my empty chair. Why do I do this? Well, I still want to take care of any physical needs before the meeting starts: use the bathroom, get a drink of water, eat a snack, etc. The video feed of my empty chair is there to assure other people that I will be participating in the meeting.

It’s disconcerting to join a videoconference and see no one else there. Doubts creep in: Do I have the right “room,” did everyone get the invitation, are they going to be here? Having everyone visible before the scheduled start — even just an empty chair — puts those fears to rest before they start.

Do not join the meeting without turning on your camera. That leaves everyone else in doubt — are you really there, or just your avatar? If I say hello, will they hear? The empty chair is a clear indication, “I will be here, but I am not yet here.”

By T-minus-2 minutes, I’m back at my desk. The meeting should not start early, even if everyone is present. Instead, use this time as you would in an actual office — chat with your coworkers, talk about the weather, share stories of your kids/pets or your progress in Animal Crossing. This gives an opportunity to sort out any audio/video issues with less stress. It’s also acceptable to use this time to make some last-minute notes on the work you left before the meeting.

By time T, the scheduled start time of the meeting, everyone should be present, connected, visible, audible, and ready to begin. The meeting organizer should announce the start, briefly state the goals of the meeting, and move forward with the agenda. You do have an agenda, don’t you?

The Elephant in the Zoom

I should acknowledge, of course, that all these recommendations imply certain lifestyle advantages. As a solo consultant and software developer, I rarely have more than one meeting per day. I almost always have the least calendar-pressure of anyone in that meeting. “Start thinking about a meeting 10 minutes early” is easy for me to say, much harder for others to do.

But I remain convinced that organizations which encourage a back-to-back meeting schedule are chasing a mirage of productivity they will never reach. Their employees are constantly distracted, stressed, and operating at less than half their potential. They don’t have enough attention bandwidth for the number of topics thrown at them daily.

“Go faster” has been the default in business for decades. But sometimes the only way to really get somewhere is to slow down.

Our computers and phones are loaded with dozens of communication apps.

I’m far from the first to ask this question. I believe it’s well-established that different modes of communication have different information bandwidth. More information is conveyed by a face-to-face conversation than an email, for example.

The conventional explanations for this are that A) text cannot convey tone, body language, or facial expressions; and B) people generally suck at writing.

But what if it’s less about how much information the speaker can convey, and more about how much the listener can receive? In other words, what if the bottleneck is not information bandwidth but rather attention bandwidth?

As of this writing, my email inbox contains 61 messages. (Down from 14,000 after a recent archiving spree.) My chat app has 36 channels open across 8 organizations. My podcasts app has 5.5 hours of content queued. And I won’t even try to count the hundreds of notifications across social media, YouTube, and the infinite doom-scroll of world news.

The only way to manage this information flood while retaining a semblance of sanity is to ration my attention. Email and chat, for example, get about 15 minutes every couple of hours. Social media gets a few minutes in the bathroom (which also sets an appropriate mental context).

So yes, that monthly all-hands meeting could be an email. That daily stand-up could be a chat message. But if it were, it would be competing with a hundred other attention-seeking missiles in the limited blocks of time I allocate to those channels. I would give it less attention, less time, less thought. I might ignore it completely.

I know I do better work when I can focus my full attention, uninterrupted, for several hours at a time. I expect this is true for most people, especially those doing any kind of creative work.

The purpose of a meeting, then, is not to convey information efficiently. It is to force an audience to pay exclusive attention to one thing, to get that creative focus pointed in a particular direction.

In the same physical space, our attention is constrained by social norms: It’s considered rude to look at your phone during a conversation or surf the web in a meeting. Remote-video meetings are challenging, in part, because the social norms of physical space conflict with the continuous partial attention habits of virtual space.

Regrettably, in many organizations, a meeting is the only way to obtain someone’s full attention, especially managers or people with responsibilities to multiple groups. I don’t have a prescription to fix that: It’s a deep problem in organizations of all types.

Hopefully, though, it helps just to acknowledge the problem. Ask yourself “Why have this meeting?” Acknowledge that the answer might be “To force people to listen to what I have to say.” But perhaps, in time, we can develop ways to ask others for their full attention — and give our full attention in return — without having to stake a claim to hour-long blocks of time.

Profiles are something I don’t think about often, if at all. Maybe I enter a few details when I sign up for a new service, but then I rarely think about it again. I have one or two photos of myself that I don’t hate, and I use them for every account.

Most of my remote jobs have involved at least some in-person interaction, usually at the start of a new project. But recently, given circumstances, I’ve had gigs where I never meet my colleagues in-person.

This has changed how I think about profile pictures. For my colleagues on recent projects, my photo on various apps — chat, email, project-tracking — is the way they see me most frequently. There are still video calls, for sure, but that’s typically only a few hours per week, far less than the time we spend interacting in other apps.

In light of this, I’ve started taking more regular snapshots and updating my profile picture every couple of weeks. I shoot close up so that my face fills most of the frame, knowing it will be displayed at thumbnail size. I make a couple of tries for a decent angle, but I don’t sweat it too much because I know I’ll be replacing it soon.

Note that I’m only talking about private communication apps here. It’s perfectly reasonable to curate photos on your public or semi-public social media accounts. But the colleagues you work with every day deserve to see you as you are, just as they would if you worked together in a physical office.

If you are someone who, like me, has trouble identifying faces from still photographs, it is especially helpful when those photographs resemble their subjects as closely as possible. As a kindness to us facial-recognition-challenged folks, please update your picture any time you get a haircut, change your hair color, or otherwise alter your appearance.

Related notes: Don’t include anyone else in your profile photo, such as your spouse or children. We want to see your work self, not your anniversary-vacation-at-Disney self. Don’t use a photo of your pet. Don’t wear a Halloween mask (you know who you are). And absolutely do not use an image that isn’t a photograph of you.

Why so much concern over something as tiny as a thumbnail picture? Because it’s all about the tiny things. Remote communication is hard. Anything we can do to make our coworkers feel even 1% more connected is worth the effort.

If you haven’t been following, here are some recent episodes to check out:

• Russ Olsen, author of Getting Clojure and Eloquent Ruby
• Jen Myers, software educator and public speaker
• Aisha Blake, founder of the musical tech conference <title of conf>

Or get the whole series in your podcasting app of choice.

I also announce new episodes on Twitter as @nomanifestos.

Again, I’m not going to recommend specific products here. What I will do is provide you with a set of criteria by which to evaluate products.

Real-time Collaboration

For pairs and small groups, the best remote approximation of an in-person meeting is a combination of real-time videoconferencing and a shared editable workspace to simulate a whiteboard. You will probably need multiple products, one for videoconferencing and several for different kinds of shared workspace.

For small groups to collaborate effectively, they need a shared workspace that all members can edit simultaneously. It is critical that all participants have equal access to the shared workspace, taking into account technical limitations such as screen size and network lag. This is where “screen sharing” tools break down, even if they support remote control: The owner of the “shared” screen has privileged access versus the other participants.

The ideal workspace will be located on a server roughly equidistant from all parties. There are a variety of solutions suitable for different audiences, from shared terminal sessions to document-collaboration products, so the choice depends on the people involved and the type of thing they want to collaborate on.

The optimal size for a remote meeting, in my experience, is 3 participants or fewer. It’s just too hard to have a productive discussion with a larger group when facial expressions and body language are filtered through the limited quality of typical videoconferencing setups. Communication styles that work when everyone is in the same room, subconsciously aware of subtle changes in body language or breathing, break down when those cues are missing or muffled.

Even in an era where consumer-grade webcams can record video at 4K resolution, bandwidth and latency are still wildly inconsistent across the internet. It’s highly unlikely that any service will be able to stream the same video quality to everyone, and it only gets harder as you add more connections. The conduciveness to collaboration is constrained by the worst connection. Even if 8 out of 10 people have a great connection to a meeting, the poor experience had by the remaining 2 will drag down the overall quality.

This doesn’t mean that collaboration within larger groups is impossible to do remotely, it just requires different tools and approaches that I’ll cover in future posts. Stay tuned.

Everyone has different preferences — weight, fit, padding, shape — so I’m not going to recommend any specific brand or model, only suggest that you invest in a good-quality product. You don’t need to spend hundreds of dollars, but I wouldn’t bother with anything under US$ 60. Try to find one with some built-in noise-cancellation. Comfort is a factor too, since you may be wearing this for hours at a time. I had to try several different sets before settling on one I liked.

The following are not adequate substitutes:

• Airpod-style earbuds: the microphone is too far away to pick up speech clearly without background noise, and the batteries die at inconvenient times
• Headphones with a microphone hanging from the cable: the microphone is poorly-positioned for good voice pickup and often creates noise when it brushes against clothing
• Bluetooth anything: Bluetooth itself is unreliable, and the audio quality on most Bluetooth microphones is poor

Microphones built in to monitors or webcams are the worst. They pick up all the noise in the room: typing, tapping pencils, squeaky chairs, your cat.

Finally, laptop built-ins are the worst of all, because the speakers and microphone are, by necessity, near one another. The sound from the speakers gets picked up by the microphone, creating a distracting echo. If you don’t have access to a headset, at least put on headphones to spare your interlocutors the sound of their own voice on a half-second delay.

[Added] Dedicated “conference call” units combining a microphone and speaker may be slightly better at avoiding speaker-to-mic echo, but the sound quality they deliver is just as bad as built-ins. Anything designed to pick up multiple voices in a room will, by design, pick up all the sound in the room. That includes ventilation, voices echoing off hard surfaces, and vibrations in the table itself. You don’t realize how loud these things are until you’re on the other end of a conference call in a noisy room. You might as well hold your meeting during a thunderstorm.

How to Use a Headset

Now you have a decent headset with an adjustable microphone. How do you adjust it?

A common mistake is to position the microphone directly in front of your mouth. That creates unpleasant “breathing noise” and distorts the sound of your voice.

The ideal position for a microphone is close to your mouth, but not so close that it is affected by the stream of air coming out when you speak. To feel what I mean, hold a finger in front of your mouth while you speak the sentence, “Podcast performance provides poor perennial profits.” Feel that? If your microphone is in that stream, every p sound is like the thump of a helicopter’s rotors to your listeners.

The most common recommendation I’ve seen is this: Place the microphone head about 1 inch (2.5 cm) from the corner of your mouth, slightly below your bottom lip.

I tried to draw this, but given my (lack of) drawing skills the results were more disturbing than helpful.

Once you have your microphone in place, don’t touch it! Make sure it is not in contact with your skin or facial hair. Keep it clear of your clothing, hair, and jewelry as you move around. The tiniest brush against a zipper or collar sounds like an avalanche for the listener.

If you read this and the previous article (and acted on them) then congratulations! You’re already ahead of most other organizations trying to “do remote.” I hope to continue this series with more recommendations based on my 15 years of experience as a part- or full-time remote employee, so stay tuned.

[Added March 11] The one exception to my headsets-only rule is if you’re willing to shell out several hundred dollars for a studio-grade microphone with a pop filter. Even then, you should be wearing headphones to prevent echo from other participants.

First, you need to get some network cables.

Wi-Fi is terrible. No, really, it is. “But my super-duper Wi-Fi router can do 200 zottabits per second!” you say. Nope, that’s bandwidth, and while you need at least a minimum threshold for audio/video, anything above that doesn’t matter. What matters are latency, packet loss, and jitter. In less-technical terms, it’s about how quickly and reliably a network can deliver a single piece of data.

Wi-Fi, like nearly all wireless communication technology, sends electromagnetic waves through the air, where anything and everything can interfere with them — walls, furniture, appliances, you, your cat — not to mention every other Wi-Fi-capable device nearby.

As Wi-Fi has become more popular, the situation has gotten worse. Even if you live alone in a cabin in the woods, you probably have at least half a dozen devices connecting to your Wi-Fi network — computer, phone, media players, “smart” devices, your cat. An apartment building or office might contain hundreds of devices, all interfering with one another.

Modern Wi-Fi networks are designed to keep working in the presence of interference, and they do a pretty remarkable job of it. That’s why you can watch YouTube in one room while your spouse is surfing Reddit in another and neither of you notices anything wrong (other than the content on Reddit and YouTube).

But videoconferencing, unlike most web surfing, is “live” and in real time. Human senses can detect delays as short as a tenth of a second, sometimes much less. The brain adapts, which is why telephones work, but only up to a point. Beyond that point, conversation becomes difficult or impossible.

Gamers have known this for a while. A few milliseconds could mean the difference between life and (virtual) death. Steam’s first recommendation for networking is wired. PC Gamer magazine agrees.

So get yourself some Ethernet cable (and adapter, if needed) and connect your computer directly to your home or office router. This is the single most effective thing you can do to improve your remote experience, especially if you’re in an apartment complex or office.

The next most effective thing you can do is get a headset, which I’ll cover in a future post.