What I Learned Looking for a New Job

Yesterday was my last day at the company I’ve worked with for the last 4 years. On Monday I start at my new position. In the meantime, I hope to be a little more creative in my personal spaces; here on the blog, over on Twitch, etc.

Here are some things I learned while job hunting:

Don’t Give a Number

In all previous job searches, I’d decided to ask for X% more than my current salary when talking with potential employers. Invariably, I never received an offer for more than that, and often less.

This time, I simply told them my current salary, and explained that any offer I received would go through a risk-reward analysis in my mind. After all, I could have stayed at my current job, even if it wasn’t what I really wanted to be doing. While this may end up wasting some of your time (see below), it can also pay off.

Imagine my surprise when I received an offer for a substantial increase in salary! We’re talking >50% here, which blew my mind. The remnants of my shattered psyche were then completely demolished when, at my next interview, I was told that they could match that offer! By the time the third company said the same, I realized that I’d been setting myself up to be underpaid by telling prospective employers how much I would settle for.

Apply Everywhere

I applied to at least a dozen companies. One of them seemed like a real long shot, as they dealt with big data management and expected a knowledge of SQL queries I didn’t have. But I applied anyway, and even took a test quiz to create some complicated queries. I was sure that was the end of the line for me there, but instead of just giving up, I did as much as I could, and documented where I couldn’t continue, and what I thought might be the next steps. And yet I passed to the next step of the process.

The point here is that it’s not always what you already know that’s most important; sometimes it’s demonstrating your capacity to learn.

Check Glassdoor

Glassdoor is a great resource for those on the job hunt. Like any set of reviews, remember that those with a negative impression are more likely to provide feedback, so reviews are likely to skew in that direction. But the one company with consistent poor reviews lived up to their reputation with me…

Once I had an offer, I reached out to the other companies I was in talks with to let them know. I was now on a time limit, and wouldn’t give up a bird in the hand for two in the bush. It was only then, in the 3rd or so round of discussions with this company, that they told me they were willing to “increase the base pay” for the role to match my current salary. Remember, this is after setting a clear expectation in the first meeting that I wasn’t prepared to leave my position without a compelling monetary gain.

It was a complete waste of time, both mine and theirs. Maybe if they had some awesome role, with amazing benefits and great culture, I could have been convinced to make a lateral move. But Glassdoor had already told me that wasn’t the case, and we promptly ended talks there.

Consider How They Treat Your Time

In the process of interviewing for a role in technical writing, I was asked to provide writing examples, do writing exercises, and all other manner of proof that I had the skills needed. The companies that immediately turned me off were the ones that asked for me to complete writing exercises for them immediately. One even asked for a personal essay, before we ever spoke!

I get it if you’re a big company and you want to weed people out of the process as early as possible, but how is a 15 minute meeting to talk going to take more time, for both parties, than writing and then reading an essay, or reviewing a writing exercise specific to that job, which I couldn’t use elsewhere?

As far as I’m concerned, this behavior tells me how that company respects (or doesn’t) your time, and it won’t end when you’re hired.

I’ve worked on open documentation repositories for the last decade. Everything I’ve written, edited, and (for the most part) discussed is out in the open on GitHub. The company I accepted a role at happened to be the only one where I knew they looked at my actual work history, laid bare as it is. While this wasn’t the only deciding factor, it showed that they respected my time by seeing what was already out there, and not asking me to rehash or reform my body of work specifically for them to consider.

Give Honest Feedback Before You Go

As I said above, I could have stayed put. I wasn’t happy, but I was paid well enough and received positive feedback for my work. I could have kept muddling through, finding solace in the fact that I was part of a great team and we were fighting through the problems together.

But I was depressed. Not clinically, just as a description of my emotional state. And I didn’t even realize it until I put in my notice. The resignation that I couldn’t change the problems affecting my work had affected my mood in and out of work. Only after getting over the dread of having to tell my lovely and supportive manager that I was leaving did I start to feel a change.

The company I just left is full of amazing and wonderful people. As a part of the technical writing team, I had a chance to interact with most teams, trying to find, consolidate, and manage the knowledge needed for customers and staff to be successful.

But the problems were systemic, and my years there showed me they were unlikely to change. I’m not going to sit here and bad-mouth them publicly, but I made sure to be respectful but honest in my exit interview. What they do with this information is beyond my control. All I could do is document the problems as best I could, providing resources for others to use in continuing to fight for change.

Moving forward

I’d been told by coworkers in the past to always be looking at what’s out there. Take meetings and see how other companies value your worth to them. Doing so may have informed me that I could be making more money earlier, but I just don’t think I have it in me. Job hunting takes a lot of time and energy, especially when doing it in earnest. And the value I place in my time and others’ is too high to waste it by pursuing opportunities I don’t intend to consider taking.

Having said that… I don’t know. I stayed with each of my last two jobs for over 4 years, which seems long compared to the job histories I look at on LinkedIn. Tech folk seem to move around every 2 to 3 years on average, but I’m not sure why that is.

This is where I’d love to get more input and feedback. Why do tech folks move around so often?

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 exempt 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. 

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!

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?

Where to learn online?

As mentioned in my last post, I’m taking advantage of this arbitrary point in the Earth’s rotation around Sol as a starting point for a renewed spring of educational self-improvement. Since then I’ve been looking into what online courses to take advantage of.
Below are some of my impressions, both old and new, of some of the online learning resources I’ve dabbled with.

Continue reading “Where to learn online?”

New Year, New Goals (just like everyone else)

My goal is to focus less of my free time on games, tv, and other wastes of time, and more on learning, reading, and strengthening my skills as a technical writer.

To that end I’ve been looking into several online coding courses. I’ve already tried some in the past, and never found one that suited me. But there’s always more options, and perhaps a permutation of two or more courses on the same subject might yield an education path I find more palatable.

The secondary advantage will be that I will have more notable things to blog about, bringing this blog back up from its slumber.

So wish me luck, and if you have any first-hand experience with self-learning on tech subjects online, please share it in the comments!

Childhood Effects on my Adult Sleep

Last night I went to Zappa Plays Zappa, the show where Dweezil Zappa and a group of very talented musicians performs Frank Zappa songs. It was an amazing show. Jen and I were especially impressed with Scheila Gonzalez, who played several instruments perfectly, including a downright amazing saxophone solo, and sang with amazing range.

Since it’s the 40th anniversary of the album One Size Fits All, they played most of the album before doing other hits. If you’re not familiar with Zappa or the album click here and listen to about a minute of it. We sat in  the third row left of center, right in front of the trumpet  / trombone / guitar player, so it was pretty freaking loud. Imagine the scene, and then guess what I did.

I fell asleep.

Several times in fact. I was following this loud, intricate cacophony of sound, and then suddenly I’m in a random dream sequence with the music in it, and then I open my eyes back at the show. I wasn’t tired before the show started, and after the album finished and they played more standard rock songs I was awake and alert again. Why would the most musically complex music I’ve ever heard performed live make me fall asleep sitting up?

Here’s my theory: as a child my parents would play lots of music, including a lot of Zappa. I would be put to bed at 7 or 8 and they would play One Size Fits All among others while I slept, in an old house with thin walls. Has my brain been trained to associate this music with sleep, to the point where it will put me under in a situation otherwise unconducive to sleep?

If anyone has any insight into this sort of phenomenon, please let me know!

The Linux Power User

There’s a whole group of Linux users out there (myself included), for whom we aren’t writing guides for. When you search for answers online, you find one of two types of write-ups: basic instructionals aimed at first timers, and advanced hacks for those who already have coding language or two under their belt.

But what about everyone in the middle? Those who know how to live in Linux, but aren’t developers? Can those who develop open-source software put themselves in the right mindset to write documentation for those who don’t know what they know? In most cases, the answer seems to be no.

Here’s an example: when I was interested in trying out Atom, I found this project, which include syntax highlighting for GitHub flavored Markdown. Great stuff, but how do I add it to the text editor? If I was only to use the maintainer’s readme file, I’d be lost on how to use it. Bad form.

On the other hand, here’s a project on GitHub from a former colleague with an excellent readme which covers not only installation. but common configurations and usage. Well done!

I’ve asked around, and I’m not the only one who feels that there’s a gap in tech write-ups. That’s why when we write guides for Linode </obvious product placement> we specify the prerequisite knowledge and link to those guides, and don’t cover anything that’s in them. But all new concepts are explained and exampled.

So if you’re a member of an open-source project, go take a look at your README. Would it make sense to someone who’s never used the language it’s written in? Do you explain how to install it, or expect the reader to already be familiar with make? Think about it please.

Culture

I came across this image on Facebook:

doubt

It inspired me to add my two cents.

I almost never repost this type of inspirational quote-in-picture media, but here’s something we need to repeat over and over.

The society and culture you live in has been carefully guided into place to push the glorification of celebrity and the perfect image. American mainstream culture is not deemed by the masses. Popular culture trends are dependent on the options set in front of the majority of people, and those options often come from the media and news sources, owned by the same people who profit from your weakness.

By creating a constant basis of comparison to an idealized image of perfection, unattainable by most, people will judge themselves harshly, and in secret. The self-doubt leads to fear, and fear is the main motivator for material consumption; either as a temporary solution, a distraction, or an escape.

The confident, self-assured human isn’t swayed by advertising for the latest health/cosmetic product. He has no need to drown his self loathing in addictive fast “food”. He doesn’t need to consume “reality” television.

Emotional stability is not profitable. Confidence is not profitable. But you are not a cash cow. You are an individual, and you are fine just the way you are.

EDIT: Changed some pronouns after a peer review. I don’t like using gender-specific pronouns when I’m talking about humanity in general, but until we decide on a gender-neutral singular pronoun there isn’t much I can do.

Never Stop Being Amazed

If you’re in tech, don’t let the constant stream of information on the latest and greatest distract you from how awesome it is to be living right now.

When I sleep, a 6” portable device with more computing power than it took to launch men to the moon sits next to me. It broadcasts wirelessly to my sound bar a computer-created piece of music with binaural beats and isochronic tones designed to help me sleep and dream.

The device also communicates wirelessly with an even smaller computer on my wrist, which tracks how much I move in my sleep. The device uses that data, along with the sounds of my snoring, to determine the best possible moment to wake me up, as I’m coming out of a REM sleep cycle.

As I go about my day my portable computer continuously streams music from the internet. As I go from home to car to office it wirelessly connects to various speakers. It reminds me when I have meetings, and alerts me as people talk to me over a half-dozen different mediums.

As I type my friend complains about the 20 seconds he has to wait for 10GB of data to transfer off his computer over USB 3.0.

I’m going through Seinfeld again on Hulu, and they have so many conundrums due to missing phone calls because they’re not home, losing people on the road and not having directions, not having the right trivial information at their disposal. If they had the same access to information that we’ve had in the last 10 years, the show would have lost half their story lines.

Here’s what I guess I’m getting at: Now is awesome. Don’t let yourself be jaded. Don’t think so far ahead that you don’t appreciate now.