Tips for using email well

Dear new developer,

Writing great emails is a key skill. For all the hullabaloo about slack, emails still rule the roost when it comes to cross organization communication. This is because everyone has email, it is auditable and uneditable once sent, and requires no special permission beyond knowledge of an email address.

Email is great at conveying information, but horrible at conveying context. It also can be unclear and ambiguous. Because email is asynchronous, ambiguity causes slowdowns and confusion more than ambiguity in conversation (where you can say something like “when you said tomorrow, do you mean Saturday or Monday, the next business day?”).

This post has some great tips on how to write great emails. From the post:

Avoid using only temporal adverbs/nouns like yesterday, today, tomorrow, two hours ago etc but include also the specific dates/times otherwise they might be misunderstood or require from recipients to check the email’s sent date/time to calculate the actual time.

and

Use bookmarkable links when you refer to something that would eventually require from the recipient to search for in another platform.

There are a number of other great tips for writing clear emails in this post. The author also provides before and after examples, which really illustrate the points.

Worth a read.

Sincerely,

Dan

Develop Denver Presentation

Dear new developer,

In a slight departure from the normal posting schedule, I wanted to announce that I’m speaking at Develop Denver on Friday, August 16. I’ll be talking about three things that surprised me when I was a new developer. There are a number of other interesting presentations across a variety of topics. Here’s the schedule (pdf). Lots of smart people, which will, among other things, let you have great conversations and break out of being an expert beginner.

You can still get tickets here. If you’re in the Denver area, hope to see you there!

Sincerely,

Dan

There are no adults in the room

Dear new developer,

One of the most shocking things I learned when I started working in a professional capacity is that there are no adults in the room.

That is not to denigrate everyone at your company, working hard to help make the place successful.

Rather, it is to say that no one knows everything and everyone is doing the best they can. (Well, most people, and it’s good to assume positive intent.)

If you go into a company expecting to be handed work on a platter and to have someone know exactly what is going on, the way that, say, a college professor knows how to teach physics 101, you are going to be disappointed. It’s much more likely that the folks who are senior to you are trying to stay one step ahead of the customer.

There are people who are more or less expert at the problem space, but I’ve only worked at one place in my life where someone was truly a master of almost every aspect of the business. And even in that place, there was a lot of uncertainty around new programs and a lot of “hmmm, will that work, let’s try it and see”.

(This isn’t isolated to the software industry, by the way. I know folks in other industries and they aren’t perfectly run organizations. Even in organizations that really matter, like hospitals, the chaos and uncertainty is there.)

So, once the maelstrom of chaos and uncertainty arrives, there are two ways to look at it

  • problem. Oh my god, no one knows what the heck is going on. What kind of place is this?
  • opportunity. Excellent, I can see that folks are grappling toward solving problems and need some help. Let me put my nose the grindstone and see how I can help.

Of course, there is some level of uncertainty that you shouldn’t accept (anything that could damage your health, ethics or paycheck, for starters). But it was sobering to me to realize that there are no true adults in the room at any organization.

Just people trying to do their best.

Sincerely,

Dan

Write a brag document

Dear new developer,

You will encounter good managers and bad managers in your career. I’ve found that one common thread for all managers is that they are busy. Busy with meetings, busy with coordination with other teams or parts of the business, busy putting out fires, busy with helping team members. Busy busy busy.

They also will likely be responsible for your career. Promotions, compensation increases, title changes. A good manager will want you to be challenged and grow and learn.

However.

The only person who really cares about your career is you.

You can help your manager help you by helping them know what you do. Sometimes this feels like an undue burden. Surely your manager can keep track of what you’ve accomplished on their team. And some do know some of the stuff you’ve done, some time.

But what you want is to help them know everything that you’ve done that you’re proud of. This helps them understand what a great team member you are, and also gives them ammunition to fight for resources (money, projects) that you deserve.

One place to put this information is in your LinkedIn profile (more about my opinion on LinkedIn). Of course, make sure you don’t reveal any company secrets (projects, launches, technologies) in this.

Another alternative is an internal brag document. Julia Evans has written a great post on writing one. This outlines one way you can help your manager (and yourself) keep track of all the great work you’ve done. It can be far more detailed since it is internal and not limited in length.

It’s not just limited to project accomplishments. You can build a bigger story. From the post:

In addition to just listing accomplishments, in your brag document you can write the narrative explaining the big picture of your work. Have you been really focused on security? On building your product skills & having really good relationships with your users? On building a strong culture of code review on the team?

I haven’t written one of these (although you could consider my blog somewhat of a brag document, I suppose. Yet another reason to start a blog). But having some kind of record of your accomplishments that you can share with your manager will help them help you.

Sincerely,

Dan

Subscribe to a weekly link newsletter

Dear new developer,

I mentioned before the benefits of participating in an online community. If you aren’t interested in a back and forth, you can often join an email list where someone will capture interesting articles on a particular subject and email you weekly. (Examples that I’ve recently interacted with: API links, dev links, craftcms links.)

These are nice because they don’t take any effort (beyond signing up). And then once a week or so, you can get the newsletter in your inbox.

A few tips about these.

  • Pick and choose. There are so many of these (because it is valuable to have developers’ attention), so google around for a bit. Good terms to search for are ‘<subject area> weekly newsletter’ or ‘<subject area> email newsletter’.
  • Read the archives first. This will give you an idea of whether you’d enjoy the content and the voice of the newsletter.
  • You don’t have to read every link. It can be overwhelming. So just scroll through the links and click on any that are interesting. You can also share with an online community, your team or a former colleague if you see something interesting.
  • Use it to explore a new technology or area of software development. Such regular content will introduce you to both jargon and people writing about the topic.
  • Don’t be afraid to unsubscribe. Easy come, easy go. If you don’t use a technology any longer, or aren’t interested, don’t clutter up your inbox. You can always resubscribe if you miss it.

I find this kind of email list to be an easy way to get up to speed and be tuned into a tech community. (If you are looking for a newsletter for a topic and can’t find it, you can start your own too! Tinyletter.com is an easy way to do this. Just be prepared to spend some time finding and curating links.)

Sincerely,

Dan

PS You can also sign up to get “Letters to a New Developer” via email too, it’s in that right hand column.

 

 

Personal projects make you a better developer

Dear new developer,

I firmly believe that having a side project makes you a better developer. This kinda sucks, because when I get home from a day struggling at the office, I don’t want to

This post covers some other great reasons for you to start up a personal project.

From the post:

[A side project] is like when you let kids color outside of the lines [because no one else need ever see the code]. You start to think and see things differently. Plus you get to try different things in the process. You could start learning a new framework and realize that you don’t like it and stop immediately. There aren’t any consequences in your personal projects.

I found a side project to be a great place to experiment with different tools and languages that I may not have used during my day job. For instance, I was able to play with a recommendation engine and a static site deployment tool.

The post also ends with tips on picking a side project, but my advice is: pick a problem that matters to you. When you are trying to find time to work on something between all the other demands on your time, you have to really want to do so, and the only way I’ve found to do that is to be really excited about the problem space.

Other tips from me:

  • You can start with a blog. If you don’t want to write code, you can just write prose. That can be a fun way to explore new technologies or business domains.
  • Don’t be pragmatic (unless you want to commercialize the project). At work you need to walk the line between beautiful code and delivery. Side projects let you focus on beautiful code.
  • Don’t be afraid to let the project go. I have done this. It’s painful, but if you aren’t enjoying the project, let it go. I’ve found a commitment of at least six months is good to ‘get over the hump’ that I encounter beginning anything, but if you’ve been doing a side project for at least that long and you find yourself avoiding it, give yourself a break of a month or two. If you aren’t interested after the break, let it go.
  • If you don’t have time for something yourself, find a project where you can help. Ask around on local slacks or meetups or check out codeforamerica.org for ideas.

The post I mentioned is worth a read in entirety.

Sincerely,

Dan

Learn a little jq, awk and sed

Dear new developer,

You are probably going to be dealing with text files sometime during your development career. These could be plain text, csv, or json. They may have data you want to get out, or log files you want to examine. You may be transforming from one format to another.

Now, if this is a regular occurrence, you may want to build a script or a program around this problem (or use a third party service which aggregates everything together). But sometimes these files are one offs. Or you use them once in a blue moon. And it can take a little while to write a script, look at the libraries, and put it all together.

Another alternative is to learn some of the unix tools available on the command line. Here are three that I consider “table stakes”.

awk

This is a multi purpose line processing utility. I often want to grab lines of a log file and figure out what is going on. Here’s a few lines of a log file:

54.147.20.92 - - [26/Jul/2019:20:21:04 -0600] "GET /wordpress HTTP/1.1" 301 241 "-" "Slackbot 1.0 (+https://api.slack.com/robots)"
185.24.234.106 - - [26/Jul/2019:20:20:50 -0600] "GET /wordpress/archives/date/2004/02 HTTP/1.1" 200 87872 "http://www.mooreds.com" "DuckDuckBot/1.0; (+http://duckduckgo.com/duckduckbot.html)"
185.24.234.106 - - [26/Jul/2019:20:20:50 -0600] "GET /wordpress/archives/date/2004/08 HTTP/1.1" 200 81183 "http://www.mooreds.com" "DuckDuckBot/1.0; (+http://duckduckgo.com/duckduckbot.html)"

If I want to see only the ip addresses (assuming these are all in a file called logs.txt), I’d run something like:

$ awk '{print $1}' logs.txt
54.147.20.92
185.24.234.106
185.24.234.106

There’s lots more, but you can see that you’d be able to slice and dice delimited data pretty easily. Here’s a great article which dives in further.

sed

This is another line utility. You can use it for all kinds of things, but I primarily use it to do search and replace on a file. Suppose you had the same log file, but you wanted to anonymize the the ip address and the user agent. Perhaps you’re going to ship them off for long term storage or something. You can easily remove this with a couple of sed commands.

$ sed 's/^[^ ]*//' logs.txt |sed 's/"[^"]*"$//'
- - [26/Jul/2019:20:21:04 -0600] "GET /wordpress HTTP/1.1" 301 241 "-"
- - [26/Jul/2019:20:20:50 -0600] "GET /wordpress/archives/date/2004/02 HTTP/1.1" 200 87872 "http://www.mooreds.com"
- - [26/Jul/2019:20:20:50 -0600] "GET /wordpress/archives/date/2004/08 HTTP/1.1" 200 81183 "http://www.mooreds.com"

Yes, it looks like line noise, but this is the power of regular expressions. They’re in every language (though with slight variations) and worth learning. sed gives you the power of regular expressions at the command line for processing files. I don’t have a great sed tutorial I’ve found, but googling shows a number.

jq

If you work on the command line with modern software at all, you have encountered json. It’s used for configuration files and data transmission. Sometimes you get an array of json and you just want to pick out certain attributes of it. Tools like sed and awk fail at this, because they are used to newlines separating records, not curly braces and commas. Sure, you could use regular expressions to parse simple json, and there are times when I’ve done this. But a far better tool is jq. I’m not as savvy with this as with the others, but have used it whenever I’m dealing with an API that delivers json (which is most modern ones). I can pull the API down with curl (another great tool) and parse it out with jq. I can put these all in a script and have the exploration be repeatable.

I did this a few months  ago when I was doing some exploration of an elastic search system. I crafted the queries with curl and then used jq to parse out the results so that I could make some sense of this. Yes, I could have done this with a real programming language, but it would have taken longer. I could also have used a gui tool like postman, but then it would not have been replicable.

sed and awk should be on every system you run across; jq is non standard, but easy to install. It’s worth spending some time getting to know these tools. So next time you are processing a text file and need to extract just a bit of it, reach for sed and awk. Next time you get a hairy json file and you are peering at it, look at jq. I think you’ll be happy with the result.

Sincerely,

Dan