The Most Important Skill of a Remote Worker: Writing Well

It's easy to say communication is important, but I never see resources for learning how to. I see examples saying you can email or instant message or call, but not much on how to turn an email into actions.

The biggest part for me is being able to write well. Good writing can keep everyone in the loop. Good writing can motivate others to get some work done for you. Without that you're on your own and likely heading in a different direction from everyone else.

But even the best writing can‘t help if no one reads it or if you’re dealing with a stubborn asshole. Phone calls and in person meetings can help, but they're less frequent and harder to organize.

When I say writing I mostly mean emails. They can be just long enough to contain a complete message. Every word needs to count and you need to decide what you want the person on the other end to do after reading it.

Try to take some techniques from good writers. Start with a hook to get them interested.

Or start with a question or request and then explain it afterwards? I know I used to wait until the last line to make my request and I'd get ignored a lot.

I recently read “On Writing Well” and the classic “The Elements of Style”. I‘d really recommend both and I feel like I’ll be re-reading them next year.

Arguments in favor of source control comments

I recently wrote out some thoughts about why comments are important when checking in to source control (in this case Subversion, but git or any other system would be the same.) They weren‘t effective in changing any minds at the time, but I thought I’d put them online anyway.

None of this is new, in fact it's pretty basic stuff that most developers pick up before they ever get hired.

  1. Your company probably has a coding standars document that says to include some brief comments in the commit message about why the changes were made. And if you don't have a document, you should make one.

  2. Source control comments create a history for the code that can be referred to later to help in understanding why things were done the way they way they were. Even on personal projects where I will be the only one to ever see the code, I commit frequently and add comments for my own reference. For example, check out this very small project from John Ressig, nobody else has committed or forked the repository, yet he still writes comments.

  1. The comments don't need to be lengthy, in fact shorter is usually better. All it should take is a few seconds to write one short sentence in the window that is already open. Something motivated you to make the change, type it in.

  2. This page on MSDN has this to say: “When something goes wrong, you can use good check-in comments to help identify where it went wrong and how to fix it more quickly. Even if nothing goes wrong, you'll be able to easily see what changes you made and why you made them.”

I feel that we all as developers would benefit by being able to see what everyone else is working on. The commit comments may not be ideal to dispel any mystery, but they do help, a lot. Even if we had meetings and extensive documentation, I would argue that the commit messages are useful for explaining details and tracking down why specifics in the code were implemented one way or another.

Goodbye Wordpress

So I've been working on migrating from Wordpress to a static html scheme. For
now I'm using Octopress to generate pages. It's working well enough for
now, but I'm still looking for alternatives.

I like static files because they‘re fast and simple to serve. I don’t have to
worry about keeping Wordpress up to date with the latest security fixes or
adding layers of caching just in case an article gets picked up on Hacker News
or Reddit. I like that Octopress uses Markdown so I don't have to worry about
html while editing. I'm currently using Texts to do my editing and I'm
looking for a good workflow from that to Octopress still.

I don't really like that Octopress is as complex as it is. Creating a theme
meant navigating through a couple dozen html templates and Sass files. And
installing all the dependencies on both my desktop and server took some time
because I don't have a lot of other Ruby software I work with on either machine.
Comments are gone for now, though Disqus may be an option later if I want them
back.

Hopefully this is the start of a simpler, more focused blog. I still have a
little tweaking to do, but hopefully all the permalinks update correctly.

Edit: I'm also moving the RSS feed back to my server. It was on FeedBurner for
ages, but I don‘t use the stats and I’m afraid it's going to follow Google
Reader sooner or later.

Edit2: There were a few broken urls that have been fixed now. Some images
appear to be broken still though.

Edit3: Already moved on to a new platform: Hexo. It can read the same
markdown files as Octopress and I like the theming process better.

Is there any reason not to use RequireJS for JavaScript modules in the browser?

I started using RequireJS on some new smaller projects a while ago. If you don‘t know, it is a tool for loading JavaScript files that are structured as modules as well as loading dependencies in the correct order. It does some other fancy things like optionally loading files after the page is loaded, plugins, and other areas I haven’t explored yet.

To me the biggest feature is the module format and dependency tracking. JavaScript has never really had any module system or method for referencing other files. The best that we could do back in the day was put all the script tags in the HTML in the right order and avoid writing code that created globals.

Now I‘m trying to make some inroads on converting a large project’s scripts over to modules.

With the number of files and size of each one, it‘s become difficult to extend them. It’s not even easy to pull a script or two out into a unit test harness at this point because it takes a while to sort out what each file assumes is already on the page.

I‘m thinking that converting the existing project over will modularize the code, maybe even split up some of the biggest files, and make it much easier to move forward with changes in the future. It’ll take a little time to refactor the code, it will really save us some time in the future. (I hope.)

On Communicating Ideas To Others

I‘ve been thinking about communication a lot lately. I’m not going to claim I‘m good at communicating. Honestly, I think I’m pretty bad at it. But I‘m trying to get better. That’s why I started this blog in the first place after all.

Lately I‘ve been trying to grow a bit professionally. I realize that as one person, there’s only so much code I can write and only so much I can do if I‘m going against the grain. If I want to make a bigger impact, I need to put in the work to convince others that my ideas are worthwhile. I may need to spend more time and energy on this than actually coding. And I’m okay with that on some level.

I‘ve always been fairly progressive as a developer. I’m interested in new and better ways to do things. That‘s been quite valuable in the past when I can get new concepts or tools in soon enough. But to do that on a project of any size, I have to convince others I code with that new technology is worthwhile, and that’s nearly impossible when you can't get people to listen to your message.

I run into problems all the time. A lot of times I don‘t feel like I’m being heard. Sometimes I try to say one thing and I think I‘m being clear as day, but then from people’s reactions I realize they interpreted my words to mean almost the opposite of what I was arguing for.

It‘s often too much for me and I don’t bother putting the energy into it. I tend to be quiet and I like spending time alone figuring things out. If I‘m feeling like I don’t have the energy to push and be assertive, I'll often go dark and work on things by myself.

Here‘s what’s been in the back of my mind:

At what point do you give up on a line of communication?

When do you just let it go and accept the status quo for what it is? And when do you keep pushing because you know there‘s room for improvement? I feel like I’ve gone to both extremes at different times. And they both suck.

It seems like some people I can instantly click with we can understand each other. Others I can exchange ideas with after some back and forth where we come to an understanding. It's rough, but it works.

And then the rare few, not only don‘t understand the words I’m saying, but it gets worse: they take my words to mean things I never intended. They assume there is a hidden meaning or motive behind my actions.

I‘ll try to clarify and rephrase as politely as I can, but it feels like they are on a different level than I am. They have a different set of information and they aren’t willing to share enough of that information for me to get to their level. They'll make assumptions and jump to conclusions that baffle me.

In one or two of these cases, looking back, it‘s pretty obvious they did have an agenda of their own and wanted me out of the way. I hope that hasn’t been the case every time, otherwise I've wasted a lot of energy for nothing.

Like anyone I get frustrated

Sometimes I get terse. When I‘m tired I give up and go quiet. I’m sick of that. I have a lot I want to get done and changes I want to make and I'm tired of the uphill battles. I need my message to get through and I start to not care if it is clean or polite anymore.

Then I get frustrated and misread messages because I assume they misunderstood what I was trying to say. At that point I feel like a jerk, so I try to stop myself before it gets to that. The whole thing saps any energy I did have for making improvements.

Thanks internet, for letting me rant for a while…