Concerns on Communication

I’m worried about us. Us as people, as a society, as a species. We’ve never been more connected, and yet we seem to grow increasingly short-sighted in how we communicate. I mean this in both the short and the long term.

As an aside, I’m not here to rail against spelling and grammar faults on the internet. Though I may twitch when I see them, they are not the current concern. They are the red herring to distract pedants.

Briefly put: In the short term we’re not taking care to construct messages that will reliably convey our meaning to a disparate audience. In the long term, we’re adopting a standard of public discourse that values the ego over the collective conscious.

Let’s start with the short term…

Careless Communication Causes Concern

Words are imperfect symbols representing ideas (see the Legend and Definition of Terms below). Do we think in the language we speak, or are we simply interpreting our thoughts with our words?

I think it’s the latter. Think back to the last time you were searching for a word to finish your sentence. You weren’t at a loss for thought. You knew what idea you were trying to convey. Maybe you were seeking the word that perfectly expresses that idea. Maybe that word doesn’t exist in the language you speak.

Careless communication risks incorrectly expressing ideas, even by your own interpretation. And that’s where we fuck up; interpretation.

After you’ve translated your thought into symbols and expressed those symbols acoustically or graphically, it’s out of your control. You’ve encoded your bitstream, and you hope that at the other end they’re using the right codec.

Does every word have the same definition for each person using it? Probably. That is to say, we could look up a word in the dictionary and generally agree that the meaning provided is correct.

But does it have the same meaning? Absolutely not. The meaning we apply to words is heavily influenced by our personal experience, I’d say more so than the definition found in Webster’s.

How much effort do you put into thinking about how your words may be read?

Did you read that before you sent it?

“I’m sorry I wrote you such a long letter; I didn’t have time to write a short one.”
– Blaise Pascal

I probably did. I don’t know you, but I know that you’re rarely in such a rush that you don’t have the time to read what you’ve written, but still enough time to have written it in the first place. And I mean read it. Don’t scan the words, speak them in your mind as if hearing them.

Are you hearing the idea you intended to extend?

Caustic Communication Creates Calamity

What about the long term? For the moment let’s ignore the problems of careless communication in the short term, and assume that everything said is always perfectly interpreted by every reader. In the current state of discourse, I’d almost find that more alarming.

So our words are meant to express ideas. But what are our ideas to us? I wish I had a better phrasing to use, because even the term “our ideas” invokes the problematic notion I find so alarming.

The majority of ideas you have are not “your ideas”. They are ideas you read or heard from others, agreed with, and adopted. That’s how we learn1. My concern with the phrasing is that it’s a supporting factor of the problem of identity construction.

You are not your ideas. The things you believe are not you as a person. They are a big factor to be sure, but you and your thoughts are separate things.

I think this is an important idea to meditate on, because I believe that associating ideas with identity is at the crux of the long term problem with our communication.

I could (and probably will) write another piece diving more deeply into the problem we as a society have with ego and self-aggrandizing on both a conscious and subconscious level. For now I’ll simply say that we have an unhealthy attachment to ideas, making them a part of our identity. I find this dangerous, because ideas should be subject to re-evaluation and adjustment or abandonment when presented with new facts. But when an idea is part of your identity, to abandon an idea is to destroy a part of your self.

So when we communicate, we’re not trying to find the best ideas that conceptualize truth for our minds. We’re largely revalidating the ideas we pad our identity with, while attacking those not in alignment.

A pause to clarify

One may misinterpret what’s written above to mean that I’m opposed to argument. Far from it, I thoroughly enjoy a good debate. And I’m not saying that when you think someone is wrong, you shouldn’t say so.

What I’m saying is that we must include a pause for self-reflection in our communication. Think about what you really want to say. More importantly, think about why you want to say it. Are you raising the level of discourse? Are you engaged in debate? Or are you defending an ego propped up by ideas that are being challenged?

Legend:

In this essay, I use italics where I’m vocalizing the emphasis of a sentence in my mind. I use commas more liberally than may be dictated in your favourite manual of style because I want the reader to pause where I would pause while saying a sentence aloud.

Definitions of terms:

Fact: In the context of this essay, a fact is only objective truth, which itself is a term I don’t have the time or education to define further, needed though it may be of late.
Idea: Loosely related to a belief in this context, I’m using ideas as a term to define a coherent thought, opinion, stance, or proposed action.
Thought: Closely related to idea, but more ephemeral. An idea can be a single thought or collection of them. Thoughts may be supporting structures providing a base or reasoning to validate or refute an idea.


  1. I am not except from this. Little to none of the ideas discussed here are my own. This is merely an amalgamation of ideas I’ve read or heard and determined valid, restructured in the form I feel best suited to convey the unified point I wish to make. 

Busted

Dream Journal Entry 2


I parked a block away, and walked towards the target house wearing a grey uniform. Tucked under my arm was a small stack of paperwork folded in thirds with a receipt stapled to the front sheet. Tools hung off my belt.

I said I was there to service a filter in the water system. She was expecting me. I don’t remember what my ulterior motive was, but I needed her gone first. I’m pretty sure I was there to steal something important.

The problem was, I really didn’t understand how the filter system worked. I faked it for awhile, but with her watching I ended up dumping the contents of the filter into the sink while the plumbing underneath was disconnected, flooding the lower cabinet.

She’s impatient, says she really has to go. Perfect! I’m from Sears after all, you can trust me to finish the job and then lock up the house on my way out. It would have worked, but she’s smart, and looked for the trademark company vehicle parked out front, to write down the numbers. Finding none, her suspicion grows visibly on her face as she intentionally avoids looking back at me. I prepared to run.


That scene faded, and I dreamt again of  the city. This time I was staying in something closer to a hostel, and complaining how no one in crowded cities can go bowling because an alley would take up too much precious real estate.

Morning came in my dream and my character (as I viewed him from third person) woke up to the starting licks of Rift. Jen was playing it to wake me up, and the scene faded.

City of Dreams

Editor’s Note: This is the first of what might become a dream journal. I’ve marked it into a new category. I’ll try to categorize my other posts similarly, so those looking only for tech posts can get to them without wading through this bullshit. ūüôā



There’s a city in my dreams, a repeat backdrop for many different stories. It’s not a real city, but the distinct features remain the same, no matter what else is going on in the dream.

It’s out towards the west coast, but not coastal, in either Canada or the northwest US. The streets are generally layed out along cardinal directions, but with just enough 45deg angles, one way streets, and circles to make it complicated to try to get anywhere in a car. But I don’t drive, I’m only ever visiting. So I walk, or I take the subway.

There’s a city-block-wide building that functions as a self-contained Chinatown, with little “streets” running through it like you’d see at a casino. There’s a subway station underneath the building. I usually stay in a hotel across the street. There’s a restaurant that stays open late, late enough that it’s usually the only option left for a meal by the time I get back.

The subway only has a few lines, and they’re circular. It’s not hard to get anywhere, but I have anxiety about missing my stop every time. I usually have business to attend towards the north side of the city, which is uphill. I take the subway, then I walk back downhill to the litttle neighborhood I’ve become comfortable with in time to get a meal before that last restaurant closes.

Sometimes my dreams repeat themselves. Sometimes it’s just a theme that ties them. But when I’m traveling in my dreams, it’s always to this city. When I venture out in a new direction and learn what’s there, it remains static like a newly rendered chunk now commited to file.

I haven’t dreamt about that city for a long time. Maybe years. But it was back last night. It makes sense that in this story it was a replacement for San Francisco, as my dream involved Pantheon, who brought me to HQ that way week before last. I wonder why it persists. Is it just easier on the brain to save and recall one imaginary locale and all its details, instead of making up new scenes for new dreams?

I don’t hold stock in the idea that dreams carry deeper meaning to be unlocked. I think they are the mind’s attempt to make sense out of synapses being fired “randomly” during the brain’s repair and maintenance while sleeping. But I wonder if the body tries to “repair” the brain where our mind’s damage lays. I wonder if a recurring theme in a dream is a manifestation of the mind’s need to have that concept examined by a consciousness that, either through ignorance or willful refusal, ignores it.

I wonder where that city is.

Tips and Tricks for CircleCI

I am not a developer, but I work with developer tools all day. This can be frustrating, because a lot of tools made for developers assuming knowledge that I’m lacking.

Of course, if that wasn’t the case there would be less need for technical writers and my work would be harder to come by!

In any case, After spending the last few days migrating my job’s documentation to use the CircleCI 2.0 configuration, here are some tips I picked up:

Non-interactive shells

This can be tricky if you don’t keep it in mind. Because CircleCI tests are run in a non-interactive environment, your output can get …funky. For example, here’s the output of sculpin generate, which we use to turn our markdown files into html, running locally through CircleCI CLI:

Here’s the output from the build on CircleCI’s platform:

Sculpin assumes an interactive shell in which it can rewrite its output as it goes. CircleCI’s environment is set for better logging, not better human readbility (as it should be).

This is of course a trivial example, as I could add --quiet¬†to my generate command to make my CI output nicer. But that’s not always the case…

Rsync output on CircleCI

Part of my build process involves copying my compiled docs to a staging environment. Our scripts use rsync, the most common choice for transferring files from A to B.

The Problem

No matter what permutation of logging flags I gave rsync, the only output I could get from my CI builds was empty, or a list of every single file it was checking for changes:

Not a critical problem, but it certainly reduces the usefulness of the output.

The Solution

While I could pipe the rsync command directly through grep, that would interfere with the while loop I put rsync in, which checks for exit codes to determine success. Instead, I constructed my rsync command as follows:

rsync --checksum --delete-after -rtlzq --ipv4 --info=BACKUP,DEL --log-file=multidev-log.txt -e 'ssh -p 2222 -oStrictHostKeyChecking=no' output_prod/docs/ --temp-dir=../../tmp/ $normalize_branch.$STATIC_DOCS_UUID@appserver.$normalize_branch.$STATIC_DOCS_UUID.drush.in:files/docs/

That’s a lot to unpack, I know. The key flags are -q, which keeps the output quiet, and --log-file=./multidev-log.txt, to redirect output into a log file. Then, once my loop has exited, I can run:

cat ./multidev-log.txt | egrep '<|>|deleting' || true

My pipe to egrep searches for the characters < or >, or the word deleting. Using the OR operator || true means that even if the grep returns no results the line will still exit with code 0, keeping my script from failing.

Now my output is concise and useful!

(By the way, I learned a lot of useful information about rsync output from this blog post, run through Google Translate.)

Dockerize for background processes

IMHO, this tool is poorly named. While it’s purpose was originally for CI builds involving multiple docker containers (I assume), it’s helpful even in a single container environment.

The Problem

I was seeing intermittent build failures coming from my Behat tests:

Behat is configured to look at port 8000¬†for my Sculpin server to serve the files it tests. The Sculpin step wasn’t failing, but rather it wasn’t starting up fast enough.

The Solution

My initial response to this problem was to add sleep 5 to my Behat step, giving Sculpin more time to initialize. But then my friend Ricardo told me about Dockerize. Because my Docker image is built from a CircleCI image, it was already installed. So I added a new step in .circleci/config.yml:

- run:
    name: Start Sculpin
    command: /documentation/bin/sculpin server
    background: true
- run:
    name: Wait for Sculpin
    command: dockerize -wait tcp://localhost:8000 -timeout 1m
- run:
    name: Behat
    command: |
    /documentation/bin/behat

Dockerize checks for a service listening on the port, and retries if one isn’t found:

Now I have one less reason for my builds to fail…

 

Do you have any tips, tricks, or answers to common “Gotchas” for continuous integration testing? If so, please share them!

Make a site, NOW!

A month or two ago I registered eastcoastamphicar.com and set up a WordPress site on Pantheon. The eventual goal was to make a web presence for my friend Billy, who restores the historic amphibious cars, and gives rides to folks whenever he can.

Today he called me to let me know that he’d be filming tomorrow for CBS new out of New York. He said he’s doing it for the exposure, that they’d plug his email and phone number at the end of the segment.

Wait, what? His email is at yahoo.com, and his phone is a land line, no texts. Sounds like he needs that website, and he needs it now!

So I took some drone footage a friend captured, some photos I’d scanned from Billy, and made an MVP for eastcoastamphicar.com. And hopefully in another hour, once Namecheap renews their DNS records, I’ll have a nice professional email address for Billy to give CBS.

Oh, look at that. It’s past midnight. Off to bed!

Idle Hands are The Hipster’s Plaything

I’m a pretty modern person. I work remotely for a tech company, I’ve lost count of the number of computers in my home (laptops, old towers, Raspberry Pi’s, etc), I even have Tux tattooed on my arm.

And yet I find myself falling into the hipster trappings of my generation; I have a turntable, I vape, and I just bought a french press. And I wonder to myself, why am I doing this? I’m a scarf and v-neck shirt away from hipster bingo!
Continue reading “Idle Hands are The Hipster’s Plaything”

Organizing Photos

This post is on quickly sorting photo libraries. If you want to skip the backstory and jump right to the commands, click here.

I recently switched my personal file hosting/sharing to NextCloud,  from OwnCloud. Among other features and improvements, it will automatically sort uploaded photos from my phone into folders by date. 

This great new feature created a glaring contrast with the many years’ worth of previous photos, mostly all in a single directory, some sorted manually by event.  The process of grammatically identifying, sorting, and deduplicating was simple enough once all the tools were lined up, but finding them was not. What follows are the tools I used to get my photos in order.

Continue reading “Organizing Photos”

How to ask for help on IRC

Hi.
Hello?
Anyone there?
My server broke, can anyone help?

As a regular IRC user, I’ve¬†seen this message many times. I’ve¬†also seen the hateful responses these intrusions generate. IRC is an older communication form (relative to the Internet), mostly inhabited by those who’ve used it for decades, and are set in their ways.

IRC is also where you’ll find large communities of people all interested in specific topics, usually tech-related. If you’re an expert on MySQL, Ubuntu Linux, Python, etc, you’re most likely found in #TOPIC¬†on at least one IRC network.

Which is why there are newcomers everyday, logging on to seek the wisdom of these software gurus. If you’re one of them, this post is for you;¬†the IRC amateur who’s venturing to Freenode or OFTC for the first time to ask for some much-needed help.
Continue reading “How to ask for help on IRC”

Why Am I a Technical Writer?

Because of how many great open-source projects have empty readme files.

Because I like open-source software, but I’m not a developer. Even when projects are documented, it’s written for other developers. The assumed level of knowledge is that of the person who wrote it. I think like a user, not a dev.

Because when beginners enter issues on GitHub, they’re met with scorn instead of compassion. And when answers are given, the goal seems to be to give as little information as possible, and make the user chase down the real answer from clues and hints.

Because I hate being told “RTFM“. If I’m asking, I’ve already read the man page. The problem is, a man page generally only lists the options, and briefly explains what they are. Not how to use them, or why you would want to.

I’m a technical writer because I want to use great software without having to know how it was built in order to use it. Because the high learning curve associated with Linux comes in part because its users hoard their knowledge, and belittle those asking for a helping hand.

I’m a technical writer because I want everyone to be able to use the software they want.

Are you a technical writer? If so, why do you do it?