This post originally appeared on Engine Yard

Say What You Mean, Mean What You Say

Code is communication. It has two audiences: the computer, and the future maintainer. How we communicate with the computer is rather objective: you either gave it the instructions to do what you really wanted, or you didn’t.

But people aren’t so easy. As computer programmers, we channel our hopes, dreams, and moods into our writing. WordPress popularized the slogan “Code is Poetry”. To me, it reads as a true statement.

There are as many ways to write code as there are programmers, and we all do it a little bit differently. There’s beauty in this diversity, but it also makes it harder to be understood. And the harder it is to read code, the longer it takes to maintain and extend it. Time is money, so this is a bummer when it comes to building a tech business.

How can we effectively communicate with other humans when we’re programming? Write code with style! In this post, we’ll explore seven rules of thumb that you can use to write cleaner code.

1. Business Value Comes First

There are many motivations that drive a programmer when she sits down to write code. Maybe she wants to be a rock star. She’s going to show everyone how smart she is by using the most arcane methods available in her language. Maybe she’s interested in functional programming, and wants to see if she can find a legitimate use for Proc#curry in a production Ruby app. Or maybe she’s ready for the weekend, and all that’s on her mind is “ship it”.

Whatever might be simmering below the surface, when we sit down to write code, we should take a step back and look at why we’re coding in the first place. Nine times out of ten, it’s so that we can help make money for the band of misfits we run with. We should set aside our plans for world domination and adopt a view that asks “how can I help us succeed as a business?” After all, that’s why we’re writing code.

Code has to work. Preferably under all kinds of conditions. The better our codebase can withstand edge cases, the less likely we are to lose business. So we should strive to write the most solid instructions to the computer that we can.

2. Do What You Came To Do

If you’ve taken the time to open your editor and start writing code, there is a good reason that you’re doing it. Whatever the specific problem you’re trying to solve, it’s best to stay focused on it. If your codebase is like most of the ones I’ve seen, there’s probably a lot of touching going on between modules, classes, services, etc.

Sometimes when you’re writing a feature, you can’t resist going down a rabbit hole. You might think: “if only we used Active Model Serializers, I would be able to change this API response with a single line of code. I’ll just do a quick refactor and put it in.”

STOP. Maybe you’re right. But do the thing you came to do. Make a note of your brilliant idea, and write a story for it when you’re done with your feature so that you can give it your complete focus later.

Don’t leave TODOs littered throughout the code with things you’d like to see done later (for example, # Need to pull this out into a background job). Write stories instead. That’s what tracking systems are for.

Being present as you code can be threatened by many things. I’ve already mentioned tempting code changes. Other threatening distractions include social media, checking the news, Slack or HipChat, and growl notifications.

If you’ve never tried timeboxing (for example, with Pomodoros), I highly recommend it. Combine them with an app like Freedom or SelfControl to keep yourself from getting pulled away, and pretty soon you’ll find yourself able to avoid context switching for good blocks of time.

3. Keep It Simple, Stupid

You’ve heard the gospel before: premature optimization is evil. Don’t begin by writing an abstract class and subclassing when you only have one use case! If I’m reading your code, I would much rather see magic strings and duplication between files than five levels of indirection between service objects that will take an hour to decipher.

When you’re getting ready to introduce a new piece of functionality, try to solve it the easiest way you can think of first. It’s classic TDD: red, green, refactor. That means when you’re starting to solve a problem and you think “this is a horrible way to do it”, stop yourself from trying to solve it the “right way”. Write it horribly! Then you’ll be able to step back and see exactly why it’s horrible, and with the help of the tests you wrote along the way, you can rewrite it in a cleaner way.

You also don’t always have to worry about performance right out of the gate. Solve the problem first. If performance is truly a concern, run some benchmarks, choose a reasonable solution, and document it so that the next person will understand what you’re doing.

4. Backspace Is Your Friend

The number one thing that clients pay me for is understanding their business. I spend countless hours grokking custom DSLs, following paths of indirection, and deciphering other complexities of code. The mental overhead is usually high for getting things done. To some degree, this is unavoidable. But there is an inexpensive way to make code easier to understand, and therefore save money: delete unused code.

Don’t be afraid to remove things that aren’t getting used. If you’re temporarily removing something, don’t comment it out with a note like TODO: put this back in after FooBar integration is complete. If you’re writing a bit of code that duplicates the functionality of something that’s already there, pull out the old version when the new one is done. Just delete it. You can get it back, I promise. That’s what Git is for.

Why should you delete it? When there’s old, dusty code hanging around that never gets called, it confuses and scares developers. We don’t know whether we are supposed to be using it, and we are afraid to delete it because we don’t want to break anything.

If you have a decent test suite, you should be confident about pulling things out as they become unnecessary. If not, take the time to write a few integration cases. Just cover the workflows that are vital to your business. Doing so will pay huge dividends in the future, because you’ll be able to remove dead code without fear, and keeping the project slim will make development faster in the future.

5. Be Understandable

Consider the following code:

1
2
3
4
5
6
7
8
9
10
11
12
13

(function(w, d, s, l, i) {
   w[l] = w[l] || [];
   w[l].push({
     'service.start': new Date().getTime(),
     event: 'service'
   });
   var f = d.getElementsByTagName(s)[0],
   j = d.createElement(s),
   dl = l != 'dataMonitor' ? '&l=' + l : '';
   j.async = true;
   j.src = '//cdn.foobar.com/script.js?id=' + i + dl;
   f.parentNode.insertBefore(j, f);
 })(window, document, 'script', dataMonitor, id);

Wat?

Just because you can write things succinctly doesn’t mean you should. Code golf is fun as an exercise, but it’s not fun to try to understand your minimal code when I’m trying to build a business. You should name things with full words that accurately describe what is happening.

Writing code that’s easy to understand is both courteous and economical. I can’t count the number of hours I’ve spent trying to decipher terse and cryptic blocks of code. It may seen on the surface like it doesn’t matter how you write code as long as it works. But when you consider the number of hours saved across a team when code is easily understood, it’s clear that how you write it can actually make a big difference.

6. Follow The Style Guide

Conventions are ways of writing that lessen the burden on the reader of having to figure out what the author intended to say. All writers have a relationship to conventions, whether it’s strict adherence, defiance, or complete ignorance.

To communicate with an audience (which you are doing when you write code), knowing the conventions of your language is of the utmost importance. Writers of prose follow the strictures of Strunk and White’s Elements of Style.

By the same token, programmers should have a basic understanding of the norms in their community. Rubyists have the Ruby Style Guide. JavaScripters are more contentious about conventions, but the AirBnB styleguide and Doug Crockford’s JavaScript: The Good Parts are popular references. Those writing Python can run Pep8 to make sure their formatting is on point automatically.

Whatever your world, pay attention to the community around you. If you conform to what people expect, you’re likely to get a lot more accomplished.

7. Always Include Documentation

As a consultant, I spend a lot of time reading through other people’s code. Every few months I find myself in a new context, and unless I’m building a greenfield project, I have to ramp up on a codebase with months to years of history.

It’s always surprising to me the extent to which teams rely on undocumented knowledge. When I’m trying to get a project up and running, I always have to reach out to somebody else at the company to get past a certain snag in the set up process. The inevitable answer comes: “oh yeah, you just need to foobar the bazqux, then it will work.”

While this process does get me where I need to go eventually, a lot of time and context-switching could be saved if the necessary hack were included in the README. With clear documentation, I probably could have figured it out on my own.

The same thing goes for comments. In communicating the purpose complex function, class, or method, your first line of defense should be good naming and clearly written code. But when the going gets rough, a few well-placed comments can go a long way.

Whatever you do, leave a trail of docs behind you. Doing so is a boon to the future maintainer of your code. And who knows, it might be you!

Write Code With Style and Compassion

It’s hard to understand code. The developer that comes after you will have to dig through a complicated folder structure to find your files, and when they get there they’ll have to decipher your variable names, dig through your dependencies to find magic values, and try to grok how what you’ve written stands for a real business situation.

To those of us writing modern, flexible languages, the possible ways to solve a problem are quite numerous. But we should realize that if we want to do our best to make our thoughts clear to whoever comes after us, our best bet is to write code as straightforwardly as we can.

We should strive to be humble. Leave behind the desire to write the most clever or efficient algorithm if it means sacrificing clarity. Blazing fast code has a time and place. But generally speaking, the money your company will save when the next programmer understands your code immediately will more than make up for the hundred milliseconds you would have saved by using bitmasking instead of a dictionary.

Conclusion

In this post, we’ve talked about seven things to consider integrating into the approach you take to writing code. It’s my hope that you weigh them, and perhaps call them to mind as you’re programming. If we all do our part by choosing to write code with style, the codebases of the world will be a little cleaner, and working with computers will be a little more fun for us all.

Until next time, happy coding!

1. 1. If the topic of code and communication interests you, I highly recommend checking out Matt Ward’s excellent post The Poetics of Coding.

This post originally appeared on Engine Yard

The world of JavaScript development can be maddening and exciting. Every day, new libraries and modules are published, and it can feel overwhelming to try to keep up. On the other hand, all of this change has its benefits. As a community, we’re heading more and more toward an ecosystem that’s easier to work in and reason about. We keep getting new candy, and it makes our lives better!

One JavaScript improvement that’s been getting some attention lately is the idea Tree Shaking. What’s that, you ask? Simply put, it’s a way to clean up your bundling process by excluding code you’re not using. We all hate bloat in our projects. Unused code increases mental overhead and makes it much harder to understand what’s going on. More importantly, it increases the size of the payload we’re sending to users in front-end projects.

In this post, we’ll take a look at tree shaking - what it is, how it works, and how to get started using it. Let’s create a cleaner build for your JavaScript project!

Where Did It Come From?

The idea of tree shaking has begun gaining traction in the JavaScript world thanks to John Doe’s Rollup project. Rollup is a JavaScript module bundler. From early on, it supported EcmaScript 6 (ES6) modules, which resulted in its creating smaller bundles. It also supports some sweet features like cyclical requires and export bindings.

But perhaps the most unique feature of Rollup is the fact that it only requires modules that you’ve actually imported somewhere. This means that unused code never makes it into the bundle. Note that this is slightly different than Dead Code Elimination. Roman Luitikov does a good job explaining this distinction in his post about Tree Shaking.

At this moment, a lot of people in the JS community are coalescing around Webpack as a build tool. Webpack’s maintainers are currently working on a Webpack 2 release. One of its interesting features is that it will support native ES6 modules without first transforming them into a CommonJS format. This is good, because tree shaking won’t work with CommonJS modules.

Recently, the estimable Dr. Axel Rauschmayer wrote a popular post about setting up tree-shaking with Webpack 2. I decided to give it a try in my colleague Marc Garreau’s Redux Starter Kit, to see what it would actually take to get tree shaking to work in a full project. You can see the result of my experiments on my GitHub.

How Does It Work?

The steps involved in tree shaking are fairly simple.

You write your ES6 code as normal, importing and exporting modules as needed. When it comes time to create a bundle, Webpack grabs all of your modules and puts them into a single file, but removes the export from code that’s not being imported anywhere. Next, you run a minification process, resulting in a bundle that excludes any dead code found along the way. If you’re curious, check Dr. Rauschmayer’s post for more details.

Setting It Up

Since Webpack 2 is still in beta, you’ll need to update your package.json to point at the beta version. But before we do that let’s also talk about our Babel preset. Typically, I use the es2015 preset, but this preset relies on the transform-es2015-modules-commonjs plugin, which won’t work for tree shaking. Dr. Rauschmayer pointed this out in his post. At the time of his writing, the best workaround was to copypasta all of the plugins in that preset except transform-es2015-modules-commonjs.

Thankfully, we can now get around this copy-pasta’ing by including the es2015-native-modules or es2015-webpack preset instead. Both of these presets support native ES6 modules.

Let’s install Webpack 2 and the es2015-native-modules Babel preset by running npm install --save babel-preset-es2015-native-modules webpack@2.0.1-beta.

You should see these packages appear in your package.json dependencies section:

1
2
3
4
5

"dependencies": {
  "babel-preset-es2015-native-modules": "^6.6.0",
  "webpack": "^2.0.1-beta"
  // etc.
}

You’ll also need to update your .babelrc file to use the new preset:

1
2
3

{
  presets: ["es2015-native-modules", "react"]
}

Remember that we need to run a minification step during our bundle in order to take advantage of dead code elemination. Change the build script to use the --optimize-minimize flag on our call to the Webpack executable:

1
2
3
4
5
6
7

// package.json
...
  "scripts": {
    "build": "webpack --optimize-minimize",
    // etc.
  },
...

Finally, update your Webpack config to make sure we’re only listing one loader for at a time. This is for compatibility with Webpack 2, since it expects a slightly different syntax in the config.

1
2
3
4
5
6
7
8
9
10

// webpack.config.js
...
loaders: [
  {
    test: /\.jsx?$/,
    exclude: /node_modules/,
    loader: 'babel',
    include: __dirname
  },
]

Taking It For A Spin

Now we have everything we need in place to run a build with tree shaking. Let’s try it out!

To make sure everything is working, we’ll need to export some modules that we’re not importing. In my example, I decided to create some useless functions.

1
2
3
4
5
6
7
8
9

// place-order.js

export function makeMeASandwich() {
  return 'make sandwich: operation not permitted';
}

export function sudoMakeMeASandwich() {
  return 'one open faced club sandwich coming right up';
}

Then in my actual project code, I only imported and used one of them.

1
2
3
4

// index.js

import { sudoMakeMeASandwich } from './place-order.js';
sudoMakeMeASandwich();

When we run npm run build, we should end up with a minified build that excludes the makeMeASandwich code. When you run this command, you’ll see an output that accounts for removed modules. In my example, I saw a bunch of warnings from dependencies such as React and Webpack Hot Middleware. I left a few of them in the pasted output below, but the line that’s of most interest of us is Dropping unused function makeMeASandwich, since that’s the code we’re checking on.

1
2
3
4
5
6
7
8

WARNING in bundle.js from UglifyJs
...
Dropping unused function makeMeASandwich [./src/place-order.js:1,16]
...
Dropping unused variable DOCUMENT_FRAGMENT_NODE_TYPE [./~/react/lib/ReactEventListener.js:26,0]
Condition always true [./~/style-loader!./~/css-loader!./~/sass-loader!./src/assets/stylesheets/base.scss:10,0]
Condition always false [(webpack)-hot-middleware/process-update.js:9,0]
Dropping unreachable code [(webpack)-hot-middleware/process-update.js:10,0]

Now if we open up the minified bundle and search for the contents of the makeMeASandwich function, we won’t be able to find it. Indeed, searching for make sandwich: operation not permitted yields no results. It works for one open faced club sandwich coming right up, though. Success!

Going Further: Shaking Dependencies

Removing your own unused code is all well and good, but it’s probably only going to be a drop in the bucket of your overall bundle. The place where tree shaking really shines is in helping remove usused code from dependencies. If you’re pulling in a whole package, but only using a single export from it, why would you send the rest of the package to your users?

Roman Luitikov’s post did a great job of walking through what it looks like to tree shake a dependency by showing what happens if you pull in Lodash, but only import and use the first function. The rest of Lodash gets thrown out, and the resulting build is much smaller!

Since Roman has already covered this, I won’t go into the details of what that looks like here, but you can see it in my example if you’re curious.

The main point to understand is that when you consider the sizeable amount of unused code that ends up in a typical JS project when you run npm install, removing it with tree shaking can yield huge savings on bundle size.

Conclusion

Being a front-end JavaScript developer comes with a specific set of concerns. Because you’re sending a large amount of code execution off onto your user’s browser, the size of your payload can get really large. We do our users a huge service by being sensitive to the amount of data that we’re sending them.

Tree shaking offers a great way to cut down on your bundle size, and it’s easy to get set up in your existing project. I’m excited to see how this practice evolves as more of the community begins to embrace it and Webpack 2 is released. In the meantime, I would recommend reading up on some other examples of tree shaking and more of the features coming in Webpack 2.

Until next time, happy coding!

1. 1. If you decide to give tree shaking a try in your existing project, we’d love to hear how it goes. Leave us a comment!

Whether you’re bootstrapping a startup or the overseer of a tech empire, there comes a time when you have to make tough decision. You’re getting ready to build (or rebuild) a new application that will be vital to your company’s continued success. What tools should you use?

As consultants at Quick Left, clients ask us to help them make this decision regularly. We’ve worked alongside many businesses as they found their way to success. We’ve also worked with a wide array of languages and frameworks. One thing we’ve learned from these experiences is that using the wrong technology can set you back by weeks or months at best, which is both costly and risky from a business point-of-view. On the other hand, placing a good bet makes it easier to scale and grow.

There are a lot of things to consider when trying to choose the right tech stack for your app. In this post I’ll walk you some of the things I usually consider when making a recommendation.

Some Basic Things to Consider

The first questions to ask yourself when making this decision are the same ones you would consider when thinking about your User Experience. Before you decide how you’ll build your app, you’ll want to decide what kind of app you’re building.

Who is your user base? What’s their demographic? Are they young? Old? Urban? Rural? Comfortable with technology? More importantly, do you expect them to access your application from their mobile device, desktop computer, or something else? Knowing whether you need a mobile or web application, or both, will narrow down your choices of tech quite a bit.

Another consideration is whether what you are making is very similar to an existing application, a riff on a known paradigm, or something the world has never seen before. If your customers are used to a native mobile experience, you will probably want to choose a native technology, such as Objective C, Swift, or Java. If you’re trying to bring a desktop-style experience to the web, you’ll probably be looking at a single page app with a JavaScript heavy front-end and a modern framework like React or Angular.

Finally, think about your timeline. Do you need to get to market as fast as possible, or do you have time to build something with a little more lasting power? Some technologies, like WordPress and Ruby on Rails, are great for getting a product out the door as quickly as possible. Others, like Go and Scala are great at solving certain problems like scalability and performance, but will take a little longer to build.

Answering these basic questions about your business will help narrow down the technologies you need to look at. After you’ve thought about them, I recommend considering the character of your company.

What Stage is Your Company In?

The tech field is home to companies of all shapes and sizes, from two guys in a basement to global corporations with hundreds of divisions. Where do you fall in the spectrum? The answer to that question has huge implications. It will shape how you structure your budget, what you do to try to draw new customers, and how you present your brand.

When it comes to choosing the right tech stack for your app, the size and positioning of your company is also of great importance. Let’s take a look at the appropriate tech stack for companies of a few different sizes.

Basement Bootstrappers

You’ve got a great idea and you’re sure it’s going to make you bags of cash. Maybe this is your first rodeo, maybe not. Either way, your goal is clear: get it built, and get it in front of people so that you can prove your concept.

For tech companies in this early stage, it’s vital for adding features to be cheap and quick. You’re almost certainly following an MVP process, which means you’re going to be throwing a lot of work out.

When you know that your code is disposable, you’ll want to use the easiest tool you can find. Some good choices include WordPress, basic PHP, or a static site generated with Jekyll or HarpJS. All of these technologies are easy to understand, and you can probably get started with them yourself even if you’re not especially technical.

In some cases, you might already know that you need to build something that will last a little while. If you’ve already proven your concept in a basic way, and need to set up a solid base that you can easily extend from, but you’re still very young, you might want to consider using Ruby on Rails or Django. Both frameworks are easy to build new features in. Plus, they have the added bonus of being widely known, which means you will find it easier to hire new developers to work on your code as you continue to grow.

Proven Market

If you’ve been in the game for a while, and you know you’re on to something with your core offering, you’ll want to approach your choice a little differently.

If you’ve made it to this point, there’s a pretty good chance that you’ve done so via an easy-to-use technology. Perhaps WordPress or a static site. Maybe you find yourself needing to add new features at a quick pace, but the tech stack you’ve been using is proving cumbersome. It was great for building a basic interface, but setting up custom features requires you to stretch it beyond its intended purpose.

At this point, you may well make the choice to switch to a new framework. You should think about your strategy. Are you planning to add a few more core features and work on refining them, or are you going to be doing a lot of experimentation for the foreseeable future?

If you think you know where you’re headed, and your main concern is scalability and stability, you might skip past flexible frameworks like Ruby on Rails and go straight for something beefier like Go or Scala. However, that can sometimes be a pretty big risk. You’re basically betting that your business will stay mostly the same for the foreseeable future, because developing in the beefier languages takes more time and money. Still, picking one of these more “industrial strength” solutions is the way to go if you want to build something that will last.

On the other hand, if you want to keep playing with secondary features as you go, you might switch to something like Rails, or Django. These technologies will give you the opportunity to play around as much as you like. The risk you take in going this direction is that you will end up with a lot of spaghetti code, because these technologies are so flexible that you can say the same things in many ways, and your developers inevitably will do just that. If you continue down this path, maintenance will get more and more challenging as time goes on.

Of course, you may find that you don’t need to make a switch yet at all. If your current stack is meeting your needs, stick with it! Delay switching as long as you reasonably can, because there’s a pretty strong chance that You Ain’t Gonna Need It!

Established and Growing

The next stepping stone of growth after you’ve proven your market and continued to grow it comes when you reach the point of being quite well-known and having tons of users. You probably have a code base that has a lot of technical debt, because the strain of doing what’s needed to keep the business strong and growing usually necessitates making some sacrifices in the quality of your code.

At this point, your main concerns are paying off tech debt, making maintenance and development faster, and scalability under load.

This is the moment when most companies begin to consider the benefits of doing the Rewrite. The rewrite is an expensive, multi-month process in which your product’s existing functionality is coded from scratch with a new tech stack (and usually, UI), then switched out. It’s “Your Company 2.0”.

At this point, you need to decide on your organizational architecture. Will you go toward a micro-services or other Service-Oriented Architecture? If so, consider the difficulty of making sure that there is clear encapsulation and well-defined APIs for each of your services. Perhaps you want to stick with a monolith, but it’s time to start over and apply the lessons you’ve learned. Or, maybe you want to move from a server-rendered page style app to a JavaScript heavy client-side app.

If you have an established and growing business and you find yourself facing this decision, you should definitely consult with an experienced system architect and weigh the benefits and drawbacks of each approach you’re considering. Because the rewrite is an expensive and time-intensive process, it greatly weakens your ability to add new features while it’s going on. Having the guidance of an skilled architect will help mitigate the cost and risk of making the switch-over.

Evaluating Technologies

At this point, you’ve asked some basic questions about what kind of experience you want to provide your users, and you’ve identified what type of company you have. Hopefully this process has helped you generate a list of potential technologies. Before we conclude, let’s take a moment to gauge each choice on its own merits.

Drawing from my colleague Laura Steadman’s article on Evaluating Open Source Libraries, I’ve created a list of questions to ask when you’re looking at a tool that you might like to use.

• Is it well-documented?
• Is there an active community around it?
• If it’s a new framework, how quickly is it changing?
• Does it have a corporate backer? If so, what is their track record in supporting technologies?
• Is it easy to test?
• How difficult will it be to hire developers to work on it?
• What does the ramp-up time for learning it look like?
• Is there something unique about your business needs that only this technology can provide?
• When it comes to hosting and DevOps, do you have resources available to support changes on your own, or does it make sense to pay for a Platform as a Service provider like Heroku or Engine Yard?

Conclusion

When you’re piloting a tech business, there are certain touchstone moments where the decisions you make can make or break your future success. Choosing the right tech stack for your app is one of these moments. In this post, we’ve looked some strategies you can use when making this choice.

First, we thought about the demographics and experience you want to provide. Next, we considered where your business is in its overall lifecycle. Finally, we went down a checklist and asked questions to evaluate how appropriate each of your choices was.

If you’re facing this decision, I hope this post has helped you face the question with a little more rationality and forethought. Best wishes for your business and success!

Until next time, happy hacking!

When you’re getting ready to build an application, there are many choices to be made. Will you choose to build it as cheaply as possible, then hope that things work out down the line? Or do you need something more resilient? If so, spending the time and money to build a quality application will pay off. Code written with craftsmanship will withstand the tests of time, changing business requirements, and user error.

At Quick Left, we believe that it’s worth taking the time to build things right. A well-written codebase saves time and money, and withstands the test of time. On the other hand, we’re also interested in doing things efficiently. If there’s a way to write quality code and save time and money, that’s the kind of service we want to provide for our clients. That’s why we use Test-Driven Development.

What Is TDD?

Test-Driven Development is an approach to writing software in which the developer uses specifications to shape the way she implements a feature. For short, we describe it as the “red-green-refactor cycle”. Before writing any code adding new functionality to an application, she first writes an automated test describing how the new code should behave, and watches it turn red (fail to pass). She then writes the code to the specification, and the test turns green (it passes). Finally, the developer takes a little time to make sure that the code just written is as clean as possible (refactor).

If you’d like to get a sense of what Test-Driven Development looks like in action, read my post about creating a custom Ruby gem, where I walk through the process step by step.

TDD has long been a favorite approach of organizations that follow Extreme Programming and Agile principles. In 2003, Kent Beck wrote the book on this approach. In the years since, TDD has enjoyed enormous success, being elevated to near-dogmatic status.

In the past couple years, some have raised concerns that the programming community is being too strict in its demand for TDD. Most notably David Heinemeier Hansson (creator of Ruby on Rails), wrote a blog post entitled TDD is dead. Long live testing., which was met with passionate reactions from people on both sides of the argument.

At Quick Left, we continue to use TDD in our daily work. Experience has shown that it’s the fastest, most reliable way to set our clients up for success. TDD consistently produces well-structured codebases that are well-structured, resilient, and easy to make changes to as business requirements evolve.

What Are The Benefits?

What are the specific ways that a test-driven approach can benefit your business?

1. It Works The Way You Wanted It To

If computer systems built themselves, they would probably be perfect. Unfortunately, computers need people to tell them what to do, which means humans have to communicate to get software written. If you’ve worked in tech for any length of time, you’ve probably experienced the frustration of a mismatch between what was envisioned in planning and how an app actually behaves in the wild.

TDD helps alleviate this problem, because the test serves as a specification for what the code to be written should do. As long as you’re writing good stories, your development team should be able to build exactly what you asked for. If your team agrees to use Acceptance Test-Driven Development, you can even write tests that describe how you want it to work in plain English!

1. Your Code Will Read Like Poetry

Because refactoring code is a built-in step in TDD, you end up with a much cleaner codebase as you go. Apps built with TDD tend to have less duplication, fewer edge cases that aren’t thought through, and a better overall architecture.

Why should you care if the code is pretty or not? It makes it easier to add features, fix bugs, and get up to speed. Every time you hire a consultant or new developer, they have to spend a certain amount of time understanding how the different parts of your application interact. This ramping up process takes much less time when the code is well-structured. Similarly, programmers can make changes (whether features or bugs) much more quickly when there’s less mental overhead to struggle with.

1. You Can See Trouble A Mile Away

Whether you decide to adopt TDD for the quality behavior or the squeaky-clean code, you’ll enjoy this nice side benefit as well: you’ll have a comprehensive test suite! That means that just about every line of code in your application will be covered by a test, and the entire thing can be checked automatically in a matter of minutes.

The benefit of a comprehensive test suite is that it alerts you to changes early. For example, if your checkout flow stops charging users’ credit cards (eek!), you’ll know it right away, because the tests will fail. It also means that if somone makes a mistake and something doesn’t work the way it was supposed to, it will be obvious. That’s good, because it will give you a chance to fix it before it goes to production. If it becomes necessary down the road, you can even start a campaign of deep refactoring without fear, because you’ll have an ironclad test suite that will remain green.

1. It Saves You Money

In my experience working with our clients, companies often spend a lot more money adding features to their application than is really necessary.

One of the main causes of slow development is miscommuncation between product owners and developers. Too often, we experience the reality of mismatched expectations, and it feels like this cartoon:

The PO asks for one thing, the developer builds something else. Then cycles are wasted going back to fix the feature, when it could have just been built correctly in the first place. By translating business requirements into specs before writing any code, you can ensure that what you want is actually what gets built.

Another huge time sink in development is an over-complicated codebase making it difficult to make changes safely. When code is complicated, it gets much harder to get anything done, because one little change over here can result in a big problem over there. When following TDD, developers can make changes with confidence and your QA team will catch fewer regressions.

Both of these time sucks cost our industry innumerable amounts of money every year. If we just adopted a TDD approach, much of this money could be spent on new innovations instead.

Conclusion

Hopefully you now have a better idea of what the red-green-refactor cycle is, and why we use Test-Driven Development at Quick Left. There’s no better way to save time and money while making sure that you have a codebase that’s maintainable, extensible, and resistant to change. Whatever you’re cooking up, I hope you seriously consider making TDD a part of your company’s culture, because the benefits are so numerous and strong!

Best of luck.

Lately, I’ve been thinking a lot about how I learn. I was a teacher before I started programming, so I spent many hours studying how people learn. Since being a developer involves constantly staying on top of the latest technologies, I’ve turned these strategies on myself in service of learning more, faster.

In a previous post, I introduced the concept of Metacognition and talked about a process called metacognitive regulation, which you can use to get the most out of your learning sessions. In this post, I’ll share some more tactical approaches that you can use to level up your learning as a developer.

1. Know Your Learning Style

Before you start applying learning strategies, it’s good to establish a baseline understanding of how you learn. One of the easiest ways to start this work is to find out your learning style.

You may have heard of the three learning modalities proposed by Walter Burke Barbe et al: Visual, Auditory, and Kinesthetic. Just about everyone can learn from all of these approaches, but we’re also more or less attuned to each of them. You can find out where you fall by taking an online quiz. It only takes ten minutes, and is applicable throughout your life.

Here are some ways to use each modality when learning technology:

Visual learners can scan project directory structures, sketch ERD and other architectural diagrams, watch screencasts, and read through source code.

Auditory learners might learn well by listening to podcasts, watching conference talks on YouTube, and reading documentation aloud.

Kinesthetic learners will feel most at home working through tutorials, experimenting with demo projects, and doing hardware projects.

Keep in mind that you might benefit from a mixture of approaches. Looking at things from a variety of approaches can give you a more in-depth understanding of what is going on.

2. Consider Finding A Mentor

This might be obvious, but one of the easiest ways to level up is by working with someone who already knows what you want to learn. For extroverts, it may work better than studying alone ever could. Even if you’re an introvert, working with a mentor can be a great idea.

There are several strategies a mentor can take to help you learn. They can suggest thought exercises or prompts for you to work on, review your code, and explain how higher level concepts fit together.

But perhaps the most valuable thing a mentor can do is pair program with you. Asking questions and making suggestions while an experienced programmer thinks through and solves a problem in a new language or framework is an illuminating experience. If you can think of anyone who knows about what you want to learn, consider asking them to work with you. Even a one-hour session can take you leaps and bounds beyond your current capabilities.

3. Timeboxing

When I was a bootcamp student, my instructor Jeff Casimir taught us on a Pomodoro schedule, and encouraged us to take the same approach in our project work and individual learning. We would focus on a single aspect of the curriculum for 25 minutes, while avoiding distractions completely. Then we’d take a 5 minute break where we would completely switch context.

By the end of the program, I was Pomodoroing my way through my entire 14 hour day, only dropping the practice for meals and an afternoon walk. Of course, this was an extreme application of timeboxing. I was trying to cram as much knowledge and experience into my head as I could. But I still turn to Menubar Countdown whenever I want maximum efficiency.

If you haven’t tried timeboxing, I’d recommend giving it a shot for a couple hours. I’ve found it most effective when you’re strict about removing distractions like company chat, text messaging, and social media. It’s also good to set an intention at the beginning of each work session.

Timeboxing as you learn keeps you focused on finding out what you want to know, without getting dragged down rabbit-holes or spending more time than intended on a topic.

4. Reading Strategies

Education research has produced a deep wealth of strategies for learning over the past 30 years. In that time, the one discipline that has been studied and thought about the most is probably reading. Being a strong reader is a crucial skill for effective learning. Reading code is no exception.

When I first started working as a developer, the importance of reading source code was the first thing I learned. When your application relies on outside packages and libraries, it’s sometimes the only way to track down puzzling bugs. At the same time, reading through source can be a great way to get to know the idioms being used in your community. I personally like to follow what’s going on with Ruby on Rails, because the community is always active and pushing the boundaries of what Rails can do.

There are a couple of reading strategies that you might find helpful when you’re trying grok a new technology.

The first is called RAP, or Read, Ask, Paraphrase. In this approach, you make an effort to monitor your understanding as you go along. The procedure is fairly simple: begin by reading a unit of text (a paragraph, for example). When you’re done, ask yourself about what you’ve read. What is the topic? What are the key points? What are the most important details? What’s the author’s attitude toward the topic? Finally, try to summarize what you’ve read to yourself. If you’re struggling, that’s a flag that you haven’t fully digested what you’ve read. It can also be helpful to perform this process at a higher level as well, paraphrasing a complete article or module of source code once you’ve read it.

The other strategy you might like to try is to approach the questions you ask yourself from a higher level of thinking. There’s a model of thinking called Bloom’s Taxonomy that lists levels of questioning according to the level of cognitive demand. The more recent version of Bloom’s Taxonomy begins with remembering as the easiest level, then progresses through understanding, applying, analyzing, evaluating, finally coming to creating as the most demading level.

A key idea with this model is that as you engage in higher levels of thinking, you necessarily employ the levels below it as well. That means that if you are creating something, you’ll also need to engage remembering, understanding, analyzing, and evaluating. Although it’s suggested that you approach the material from a variety of levels, a study conducted in 1981 showed that using more higher-level questioning leads to better factual recall and application of thinking skills.

Here are some specific ways you can apply higher levels of thinking when learning tech.

When you’re trying to understand why something is done a certain way, ask for evidence. How do you know that a linked list is more performant than an array? Look at a benchmark!

You should also ask for clarification. Find out how the details work. Don’t be satisfied that something works, find out how.

Make connections between what you’re learning and what you already know. For example: “I know how to use Rake in Ruby to run builds and utility tasks. How do I solve that problem in JavaScript?”

Ask hypothetical questions. If you learn how to use a certain method, ask yourself: “what would happen if I passed it nil instead?” The answers to thought experiments like these can really illuminate the inner workings of an API.

Similarly, you can consider cause and effect. “What is likely to be the effect if I do X?”

Finally, engage in some self-reflection after reading by summarizing what you’ve learned. Ask yourself for one or two key points at the end of each learning session. Say them out loud, or write a blog post about them. Ask yourself what still feels unresolved - what do you not understand? That can give you a good jumping-off point in what to look at during your next session.

5. Visual Learning Aids

In addition to reading strategies, education research has produced a large number learning aids with a proven track record of success. You may have used some of these when you were in school and forgotten about them. Why not try experimenting with them again as an adult?

KWL Chart

The KWL Chart is a great way to guide yourself in prioritizing what you want to learn about. The acronym stands for “Know”, “Want to Know”, and “Learned”.

To use a KWL chart, make three columns on a piece of paper or electronic document, and give them headings of “K”, “W”, and “L”.

When you begin a learning session, choose a topic. Before you read anything about it, brainstorm words, terms, and phrases representing what you already know about the topic, and record these in the “K” column.

Next, ask yourself what you think you’d like to know about the topic and record it in the “W” column. In this step, you are setting your intention for your learning. You’re also giving yourself a map of the things you need to focus on. As you begin to do your research, you can always add more things to the “W” column to investigate later on.

Finally, as you read about your chosen topic, record what you find out in the “L” column. This isn’t a place to take extensive notes. Just write down key phrases that will help you remember the broader concepts you learned about.

Venn diagram

Venn diagrams are a widely known way to explore the relationship between two different sets of data. When it comes to learning, they can be really helpful for understanding the distinction between two languages or frameworks.

For example, imagine you are a front-end JavaScript developer with experience in Backbone, and you are trying to learn Angular. You might draw a Venn diagram with Backbone in one circle, and Angular in another. To begin, you could fill in some of the things you know about Backbone in its circle. You might write down “models automatically integrate with a REST API”. Then as you read about Angular, you can fill in its circle. You might write “ngModel reflects data between the DOM and scope directive”. In the middle, you can record things that they share. For example, “AJAX requests wrapped by internal library with convenience methods that return a promise”.

This tool might seem superfluous at first. What’s the point of writing it down if you already understand the distinction? But having everything laid out in front of you visually can really help you get a mental map of the relationship between concepts. Also, approaching your research with a mind that’s looking for similarities and differences in relation to something you already know activates your prior knowedge. And it can lead you to ask different questions than you might have otherwise.

Concept Map

Another diagram that might be familiar to you is the Concept Map. A concept map is basically a bunch of boxes connected by arrows. You connect the boxes from top to bottom with arrows that represent causation.

When I first began to study computer programming, I was struck by how similar the evaluation of a program is to the playing of a piece of written music. A program reminds me of Impressionistic Music, where the same idea shows up in different contexts as a piece progresses.The “playing” of a program involves the computer interpreting the current line of code, and every time it encounters a variable or method call it hasn’t seen yet, it finds the named variable and interprets it in the current context.

Following this line of unfolding logic, we begin to discover lines of causation in our programs. Drawing these threads as a concept map paints a picture of the whole that you would not see otherwise. Once you have that bigger perspective, it’s easier to understand where to look for bugs as they crop up, and know what to do first when you’re trying to build a new feature.

Conclusion

Knowing your own learning process is a great way to make sure you’re spending your time wisely when you sit down to investigate new technologies. Once you’ve established a baseline, the hacks we’ve looked at here can be a great boost level up your learning as a developer.

In this post, we’ve talked about finding out your learning style, finding a mentor, timeboxing, using reading strategies, and visual learning aids as quick wins you can leverage to learn more, faster.

I hope you try some of these and find them of some benefit. Best of luck!

At Quick Left, we spend a lot of time thinking about how we learn.

As consultants, we find ourselves in a new code base, or coming to terms with a new business domain, on a regular basis. Getting ramped up on code is the name of the game, so effective learning is an essential skill for us.

Even if you’re not a consultant, knowing the lay of the land when it comes to the latest and greatest technologies is essential if you’re a developer. Programmers spend a lot of cycles tinkering with “the new hotness”. For every framework or language that does eventually see some level of success, many others fail. Because of this, we inevitably invest some time learning things we’ll never use. It’s important to be efficient in our learning, to minimize wasted time and effort.

Other programmers ask me about some of the strategies I use in my own learning. Because I used to be a teacher, I’ve spent a fair amount of time thinking about how people learn. In this post, we’ll talk about how to examine your process so that you can figure out how learn best as a developer.

Introducing Metacognition

In education research, there’s a term called metacognition. It means being aware of your own knowledge and being able to think critically about how you think. The U.S. Department of Education’s TEAL project has many great resources exploring the topic. This article gives a good primer on the specifics of researchers break metacognition down.

To simplify, we can talk about two main aspects of metacognition: metacognitive knowledge and metacognitive regulation.

Metacognitive knowledge means what you know about yourself as a learner and how you approach problem solving.

Metacognitive regulation refers to ways that you hack your process to help control the outcome of your learning.

When you’re beginning the process of examining your learning, it can be helpful to begin by establishing a baseline of metacognitive knowledge. We’ll take a look at one of my favorite tools for doing this, finding out your learning style, in a future article.

Once you have a basic idea of how you learn, you can begin apply metacognitive regulation strategies to level up your learning. As you continue to use these strategies, you will expand your self-understanding as a learner (increasing your metacognitive knowledge).

Using Metacognitive Regulation

Let’s take a look at how to apply metacognitive regulation to improve your learning.

There are a number of activities you can use to regulate your learning, and just about all of them fit within the following pattern: identifying intention at the outset of learning, checking in with yourself throughout the process of learning, and summarizing the result afterwards. Educational research summarizes these three phases by labelling them Planning, Monitoring, and Evaluating.

For the remainder of this article, we’ll look at some questions to ask yourself during each of the phases. The questions listed come from Fogarty (1994) in this article.

Planning

You can begin your learning session by considering how to approach the task you are about to complete. Begin by listing the skills and strategies you have at your disposal, and identify which one(s) are appropriate for what you’re trying to do. For example, when learning a new JavaScript framework, you might choose a Venn Diagram as a tool that fits what you are trying to do - learn about something just a little different from what you already know. As you prepare to begin, it’s also a idea to decide how long you will stay focused, and how often and for how long you will take breaks. Timeboxing can really help you stay focused for longer periods of time.

Questions to Ask

• What am I supposed to learn?
• What prior knowledge will help me with this task?
• What should I do first?
• What should I look for in this reading?
• How much time do I have to complete this?
• In what direction do I want my thinking to take me?

Monitoring

Once you’ve set your intention for your learning session, you begin. As you go, it’s a good idea to monitor your comprehension. Giving yourself this kind of feedback is one of the strongest tools you can use to make sure you’re actually “getting it”.

Whenever you finish reading a section of documentation or a block of source code, you can ask yourself “how would I summarize what I just read to someone who knew nothing about it?” If you struggle to answer, that’s a signal that you should go back and read more deeply.

You can also keep track of how far you’ve gotten relative to your goal. “What percentage of the documentation have I read? How much longer will it take me to read it all?”

Finally, it can be very helpful to become aware of distracting stimuli as they arise (I’m looking at you, Growl notifications!), and consider removing them.

Questions to Ask

• How am I doing?
• Am I on the right track?
• How should I proceed?
• What information is important to remember?
• Should I move in a different direction?
• Should I adjust the pace because of the difficulty?
• What can I do if I do not understand?

Evaluating

As you conclude a learning session, you should reflect on your what just happened. Identify the higher level concept(s) you just read about, and assess whether you would be able to put what you learned into practice by using them to build something. It’s also really helpful to set yourself up for future success. Ask yourself what more you want to know about the concept, sketch a plan for your next learning session, and identify other resources you can use to find out more.

Questions to Ask

• How well did I do?
• What did I learn?
• Did I get the results I expected?
• What could I have done differently?
• Can I apply this way of thinking to other problems or situations?
• Is there anything I don’t understand—any gaps in my knowledge?
• Do I need to go back through the task to fill in any gaps in understanding?
• How might I apply this line of thinking to other problems?

Conclusion

Being a programmer is tough work. As if solving complex problems and debugging dependency issues weren’t enough, we have to stay up on the latest technologies, and continue learning all the time to keep abreast of the pace of technology. Sometimes trying to organize that process can feel like throwing spaghetti at the wall and seeing what sticks. But our time is precious, so we would like to make the most of the it when we sit down to learn.

In this article, we explored educational research on Metacognition - awareness of our own knowledge and learning process. We explored the Planning-Monitoring-Evaluating framework. This approach gives us a way to break down a learning session and ask ourselves self-reflective questions along the way to make sure we’re getting the most out of our time.

In a future article, we’ll take a look at some more specific strategies that can also be used to level up your metacognitive knowledge and regulation efforts.

Until then, best of luck, and see you on the interwebs!

This post originally appeared on The Quick Left Blog

Part 3: Publish

In this three part series, we’re exploring what it takes to break into the technical blogging space. In the first part, we looked at initial steps you can take when preparing to write. In the second part, we explored how to to get into a good writing flow during the actual writing itself. In this, the third and final part of this series, we’ll talk about one more aspect of how to write a technical blog post: getting as many people to read it as possible.

Survey Your Kingdom

So you’ve generated your blog post idea, thought about your long-tail keyword, written your blog post, proofread and edited it. It’s time to think about pushing your little bird out of the nest and seeing how she flies.

First, take another look at what you’ve written. Is there anything you left out? Are there parts you’ve included that don’t really belong? Maybe you can split them out and use them for another post. Your readers will appreciate it if you stick to a single topic. It makes for an easier time digesting what you’re talking about.

Along the same lines, take a look at the length of your post. If it’s really long, consider splitting it into a series. I’ve found that the best length is around 750-1000 words. After that, posts tend to lose focus, and readers tend to check out. Plus, when you’re publishing a series, you have more chances to promote yourself.

When you’re sure that you’ve got your post(s) tightly focused, you’re almost ready to publish. There are just two more things to consider: SEO and scheduling.

Optimize for SEO

Since you want to get as much traffic as you can once your post goes live, this is a good time to go through your post and make sure that you’ve done what you can to get good Search Engine Optimization (SEO).

Here are some things to consider. Is your long-tail keyword phrase in all of the following places? The page title, main headline, repeated a couple of times in the body, the meta description and page URL? It’s also a good idea to include several images (don’t forget the alt tags - set one of them to your keyword phrase), links to pages internal and external to your site, and a set of relevant meta keywords. For fun, you can also view your page as it appears to a search engine bot using SEO Browser.

Build The Buzz

Ok. Your content is all set. All that’s left is to put it out into the world. Before you click “publish” think about how you’re going to do send it off. A blog post is not like a software product. A soft launch is usually not a great idea.

When I’m thinking about releasing a post, I recall my days in the music industry. There’s some common wisdom in that industry about releasing an album that goes like this. You want to slowly build the buzz, like a swelling wave, in the weeks before the album drops. Then, you drop it right when the wave is at its peak. The number of sales you make in the first week is greatly indicative of how well the album will sell over time.

While this wisdom may not fit exactly for tech blog posts, as they can stay relevant or even become more relevant as the industry changes, it’s still worth thinking about “the wave swell” when getting ready to publish a post. Good ways to build the buzz include: reaching out to influencers before you publish, discussing your topic and related topics on Twitter and Hacker News, and piggybacking on trending hashtags to get people thinking about what you’re writing about.

Ideally, by the time you go live, you’ll just be continuing the conversation that’s already been happening. Your post will come out right on time.

Schedule Release

Going along with the idea of building the buzz, be intentional about when you plan to publish your post. You can probably configure your blog platform and social media accounts to publish content at a specific time.

Find out the times when your target readers are most likely to see that your article came out, and publish then. Follow up with scheduled tweets.

If you know there’s an event related to your post coming up, plan to publish just before or after that event. For example, you’re writing about a new feature in Rails 5 feature and it’s coming out on Christmas, plan to publish your post during the week surrounding Christmas.

If you’re a prolific writer, you can space out your posts to build on your own buzz. If you have two posts ready to go, don’t publish them a day apart. Give the first one a little time to get some traction, then hit your audience with the second just as they’re beginning to forget about you. This works especially with a series.

Spending a little time to think about when you should publish you post can go a long way toward getting your voice heard by a wider audience.

Shout It From The Rooftops

This final point is probably obvious, but you’ll want to promote your work as extensively as possible once it finally goes live. Here are some good places to self-promote:

• Twitter
• Hacker News
• Lobste.rs
• Reddit
• Quora
• Facebook
• LinkedIn
• Stack Exchange
• Smashing Magazine
• Medium
• Pointer.io
• Paper.li
• Slack Communities
• Coworking space forums

At a minimum, I recommend promoting your post on Twitter, Hacker News, Reddit as soon as it comes out.

If your blog allows comments, or if you post to Hacker News or Reddit, you’ll probably begin to get some questions and hear some opinions. Take the time to respond to them. The more you engage with people, the more they will appreciate and share your writing.

Wrapping Up

Over the course of this three part series, we’ve followed the entire cycle of how to write a technical blog post. Starting from the barren field of your mind with nothing but doubts in part one, and we traveled through the process of how to actually write posts in part two. With this post, part three, we’ve come all the way to the end: SEO optimization and self-promotion.

I hope this series has given you the tools you need to enter the world of technical blogging. Although blogging can seem overwhelming at first, it’s actually not as difficult as it seems. Once you’ve written a post or two, you’ll begin to discover a process that works for you. People will start to recognize you around the web (and around town). At that point, you’ll be building on your past successes. Promotion will get easier too, because people will already be familiar with your work.

Best of luck to you in your writing career. I look forward to reading what you come up with!

This post originally appeared on The Quick Left Blog

Part 2: Write

In this three part series, we’re looking at some of the best ways to get into a good flow as a technical blogger. In the first part, we talked about some initial steps you can take to get psyched up when figuring out how to write a technical blog post. In this, the second part of of the series, we’ll talk about how to do the actual writing itself. We’ll explor some effective structures you can use to organize your posts, thoughts about the creative process of writing, and how to make sure your content is as good as it can be.

Define Your Structure

So you’ve got a topic, you’ve identified a long-tail keyword, and you’re ready to start writing. You put your text editor in distraction-free mode, don your noise-canceling headphones, and get ready to dig in. But where to begin?

I recommend treating your first session on a given post as a scaffolding-building session. Don’t expect to get into details. Forget about jokes and memes. Just sketch an outline of what you want to write about.

There are quite a few good ways to structure a blog post. You don’t have to reinvent the wheel. Just pick one of these basic approaches, and it should get you where you need to go.

The List

You know what I’m talking about. Titles like Five Ruby Methods You Should Be Using are gold. Potential readers know titles like this are a cheap shot, but they can’t resist clicking the link anyway. That’s why it’s called click-bait.

If you’re writing this kind of post, the structure is obvious: write an intro and a conclusion, and slap the five Ruby methods and their explanations in the middle.

The How-To

So much of our industry is about learning new technologies and new ways to do things. Developers need to understand “how to do X” every single day. When they google for it, they will probably type “how to…” If your post begins with those words, perhaps it will be the one they find and read.

Writing a how-to article is a little more complex than doing a list. I usually break it down like this:

1
2
3
4
5
6

1. Introduction
2. Introduce a theoretical coding situation
3. Write the test for what you want to solve
4. Make the test pass
5. Repeat steps 3-4 until the point is made
6. Conclusion that includes a link to the code on GitHub

I used this structure in my Wrapping Your API In A Ruby Gem post, and got a lot of great feedback from readers.

The (Five) Paragraph Essay

If you’re writing an opinion or agile process piece, the basic Five-paragraph essay style is a great way to organize your thoughts. If you went to high school, you’re probably familiar with this layout, so it can be a comfortable choice to reach for. To write an essay think about how you’ll introduce your topic and assert a thesis. Next, prove your point with supporting arguments. Finally, summarize and reiterate your argument in the conclusion. Your outline will look something like this:

1
2
3
4
5

1. Introduction & Thesis
2. Supporting Point 1
3. Supporting Point 2
4. Supporting Point 3
5. Conclusion

The Well-Actually

At Quick Left, we do a lot of joking about being a neckbeard. There are a lot of smart people that work here, and more often than not, they have strong opinions about how to do things. Sometimes when one person begins to make a statement, an opinionated colleague will correct them with a sentence that begins with “well actually…”

“Well actually” is a great phrase, full of tension. In fact, you can build an entire blog post around the drama of this tension. Some of the most interesting articles I read are ones that follow what my mentor Jeff Casimir called “the hero’s journey”.

The basic breakdown of the hero’s journey story goes like this. First, you write about “I always thought that foo worked like bar”, or “I’ve always solved foo by doing bar”. Then you move on to say, “one day, I decided to solve foo by using baz instead”. Finally, you wrap the whole thing up with “but it turns out that the correct solution is neither bar nor baz, but qux”. This is your “well actually moment”.

These kinds of posts can be fascinating to read because they follow a story arc, and they provide more suspense than you get in flat structures like lists and how-tos.

Interlude: Let It Simmer

Deciding on a topic, generating a long-tail keyword, and sketching out your basic structure is pretty good for a first day’s work on a post. At this point, I usually like to leave the post alone for a while and let it simmer. I’ve found that when I take a break and give it a little space, my subconscious gets to work on exploring the main points I’ve set out for myself. When I come back, I find I have plenty of ideas of what to say. When I take some space in between writing sessions, the resulting post tends to be a lot richer than when I force my way through in a single sitting.

Fill In The Details

After you’ve taken a bit of a break and you’re ready to come back to your writing, it’s time to actually do the hard part. At this point, I typically feel that I’d like to do anything but sit down at the keyboard. I can think of a million distractions: “I’ll start writing right after I go get a pumpkin spice latte”, “just as soon as I send this email”, or “I think I’ll check Reddit first”. All of these impulses are what a mentor of mine once called anything to avoid buckling down.

So how do we overcome the feeling of anything to avoid buckling down? My favorite way to deal with this problem is to set up a ritual. I won’t get into the details of what mine entails, but here are some things that can be helpful: put on a specific kind of music, remove social media, email, and chat distractions, set up a different mode in your text editor, drink a certain coffee beverage. You can get even more superstitious if you want to. But the basic idea is that by identifying a series of things you do before you write, you can train your brain to get “in the zone”.

Once you’ve gotten in the zone (however it is that you do that), just start writing. You know the phrase “genius is 1% inspiration and 99% perspiration”? This step - filling in the details - is the perspiration part.

The key thing at this stage is to let yourself get into flow state. As you start to express an idea, you’ll be tempted to stop and think “is that good enough”, “is that really accurate”, or “could I have worded that better?” I recommend just letting it come as it will, and put off the judgements for later. Interrupting yourself to evaluate your writing disrupts your flow. If you’re a programmer, think of it as a TDD exercise: first make the idea come out, then refactor.

Often times, you’ll have to complete a couple of sessions like this before you get through your entire structure and have a complete first draft. Each time you sit down to write about it, you have to get back into the flow. Just follow your ritual and keep working. You’ll be through it before you know it.

Write A Conclusion

There’s a bit of an art to writing a conclusion section. On one hand, you want to reiterate and summarize the high-level concepts involved with what you’ve been talking about. On the other, you want to encourage the reader to think about the wider implications of the subject. How can it be applied to other situations? How can what you’ve been talking about be extended illuminate a higher level of understanding? For example, if you were writing about Stripe integration, maybe talk about how your post fits in the broader context of e-commerce.

The conclusion is also a great place to encourage people to take some sort of action on what they’ve learned. Whoever’s hosting your blog post would probably like to have the readers interact with their website. You can push them to do this by linking them to relevant content elsewhere in the site. Or you can use a P.S. section encouraging them to leave a comment on your post.

Proofread It (Twice)

Once you’ve completed your conclusion, your first draft is done. Take another break and get some space from the post. Shift your mindset from “getting stuff done” to “let’s clean this up” instead.

Remember above when I suggested you put off judging or evaluating your work? Now’s the time to invite that impulse back in. It’s time for everyone’s least favorite part of writing: proofreading. You need to do it. Read through what you’ve written and make any changes that suggest themselves. Then read it aloud and see how it sounds. Make more changes. Pretend that you are a member of your target audience and read it from their point of view.

The more times you repeat this process, the more clear and understandable your writing will be. Aim for brevity and precision. Long sentences are hard to understand. Only write as much as you need to to get your point across, cutting out extraneous words and explanations and really tightening up your word choices.

Ask For Review

It’s a really good idea to get another set of eyes on your writing. If you’re lucky enough to have an editor, they will give you great ideas for improving your phrasing, word choice, and structure. If not, reach out to your peers to see if any of them are willing to help you improve your work. Especially target those you think already know the ins and outs how to write a technical blog post. The more people you can get to check your work before you release it to the world, the better.

You can also ask someone in the role you’re writing for to review it. If there’s nobody on your team in that role, try reaching out to a popular influencer on Twitter or elsewhere on the web. In fact, this is also a good thing to consider doing for promotional purposes. Reaching out to major influencers early and gathering their feedback on your topic might lead to them sharing your content, which will dramatically improve your traffic.

Once you’ve solicited some help, take your reviewers’ advice to heart. You don’t have to incorporate every single change they suggest, but try to keep in mind that they’re not out to criticize you personally. They’re trying to help you, and the places they have trouble understanding your language are good spots to polish up the way you present your ideas.

Once you’re done proofreading, editing, and making changes from reviewer comments, you’re almost done writing. But first, there’s just one more thing. Proofread it again. I’m not kidding :)

Wrapping Up

Even if you know what you want to write about, the process of actually getting the words down can be hard if you haven’t done a lot of writing in the past. In this post, we’ve looked at some cookie-cutter structures you can use to scaffold your post, the importance of giving yourself some space between writing sessions, and tips for proofreading.

Stay tuned for the third and final part of this series, where we’ll explore how to draw more visitors to your post using SEO best practices and how to promote your writing on social media for the most benefit. See you then!

This post originally appeared on The Quick Left Blog

Part 1: Prepare

Content is king. Bill Gates predicted it in 1996. Much of the money made online today is in content. In the tech world, where languages and frameworks are here today and gone tomorrow, this is doubly true. Developers, managers, and CEOs of technical companies spend an enormous amount of time understanding their chosen tools, the next hot thing, and how to stay relevant.

It’s no wonder so many startups host blogs on their sites. Blogs drive traffic to your site, increase your visibility, and elevate your brand in the tech world. So how can you get a piece of the action?

In this three part series, we’ll explore some strategies you can use to generate ideas, produce clearly written blog posts, and effectively promote your work on the internet. In this, the first part of of the series, we’ll talk about how to get started as a technical writer: overcoming mental resistance, generating ideas, and starting with your audience in mind.

Get Psyched Up

Figuring out how to write a technical blog post can be overwhelming if you’re not used to it. Many people find it hard to choose a topic. A lot of times, it comes down to feeling like you don’t know enough about anything to write about it. But if you think that you have to be an expert before you start writing, think again.

I don’t know how many times I’ve heard people say: “I would write about (insert technology) if I knew a little bit more about it”. It’s common to feel uncomfortable with the idea of publishing a piece telling the world “how you should do X”. But fret not. This is just a little bit of imposter syndrome.

Try on a different perspective: think of blogging as a learning process. Maybe you’re not the world’s foremost expert on Flux. It interests you, but it’s a little bit hard to wrap your head around. Instead of feeling like you have to be an experienced Flux developer before write about it, think of it as the path you’ll use to understand it. There’s no better way to understand something deeply than to teach it.

1
2
3

If you want to learn something, read about it. If you want to understand something, write about it. If you want to master something, teach it.

- Yogi Bhajan

Blogging can be a great way to give structure to what you want to understand about a topic. It can also serve as a roadmap of how you will get to mastery. What are the components of the topic? How can you break it down? What little pieces can you try to grok that will help you see the big picture? These are the questions you have to ask when you’re teaching something. They also happen to be the questions you’ll need to answer to learn something!

You can also treat blogging as a way to document how to solve a specific problem so that you can look it up later. Once you’ve gone through the struggle of figuring out what’s going on, you’ll have a handy place to go back to and remind yourself what you did - in your own writing! Might as well open source it.

There have been a number of times in my blogging career when people have read one of my posts, then reached out to me and and asked: “you’re an expert on X, what can you tell me about this one arcane part of how its written?” In almost every case, it was the first time I’d even tried to understand the topic!

Brainstorm

So you’ve gotten past your initial reservations about writing, it’s time to choose a topic. Figuring out what to write about can be just as daunting as deciding to write. But once you know where to look, you’ll find that fertile ideas present themselves every day.

Here are a few of the strategies I use to come up with topic ideas.

As a consultant, I work on a lot of different projects. Each one usually has one or two unusual problems that have to be solved in a novel way, either due to the business domain or idiosyncracies of the tech stack. I keep an eye out for things like this and write about them. They usually make for an interesting read for curious developers.

I also keep an eye out for ways that I am percieved to stand out by client teams. Sometimes I’ll suggest a certain way of doing things that is new to a team, and I get a lot of feedback about what a great idea it is. For example, the Quick Left Pull Request Template is often quite appreciated.

Similarly, the particular business situation that a client company finds itself often lends itself to a process-related post. I recently did some work for a company whose codebase hadn’t been worked on for a while, so I wrote this post and this post to help technical leaders in this situation find some direction.

In all of these examples, you could just as easily leverage your business or technical situation even if you’re not a consultant. Think about your codebase’s “gotchas”, ideas that new hires have brought in, and the quirks of your particular niche in the business world. These are rich sources of post topics.

If none of these situations applies and you’re still drawing a blank, you can always go the old fashioned route: google it. Sites like Buzzsumo, SEMRush, and Alexa are great for generating ideas. I also recommend Google Trends for figuring out what’s people are asking about a given topic. All of these tools are great ways to identify things to write about that people will actually be interested in reading. This great for generating page views.

Consider Your Audience

While we’re on the topic of page views, you should probably consider who it is that you’re writing for. Is it developers? Your product owner, scrum coach, or CEO? Maybe marketers or salespeople? What role do they play in the tech industry?

It’s vital to have an idea of who you want to read your post. Knowing this enables you to answer an important question: what problem(s) does this person need to solve in order to do his/her job?

When people face a difficulty that they don’t know how to solve, they google the answer. If your blog post comes up at the top of the search results, they’ll probably read it. On the other hand, some folks will look for the answers to their questions in other places online. Where does your target audience spend their time? Are they hanging out on Reddit, Stack Exchange, or Quora? Think about how you can get your post there, and write it such that it will be accepted by that online community.

Identify A Long-Tail Keyword

You might think that marketing your piece is something that comes after you’ve written it. But considering how you will promote your post before you write it can help focus your writing and lead to a warmer reception when you publish. One of the easiest wins you can make early on is to choose an effective title.

I typically try to match my titles with a well-chosen long tail keyword. Long tail keywords are specifically targeted 3-4 word phrases meant to be found by readers researching a particular topic.

Because single-word rankings in search results are very competitive, it’s easier to get a higher search result rank for a multi-word phrase than a single keyword. Usually, it’s best to think of the most compact way to express what you’re writing about using common language.

For example, the long-tail keyword for this post is “how to write a technical blog”. It’s more likely that someone would search for that phrase than something longer like “steps to follow when you want to publish your first technical blog post”. On the other side, it’s more likely that my audience will find my post than if I had used something more generic like “tech blogging”.

Generating a good long-tail keyword is a bit of a fine art. If you have any friends that are marketers, ask them for help. Barring that, you can google terms similar to your idea to see what people are asking about, use a thesaurus, or follow the suggestions in this article.

Wrapping Up

Getting into the head space of writing a blog post can be difficult at first. But when you treat it as a learning process and break the process up into small, manageable tasks, it becomes easier. In this post, we’ve looked at how to rethink your mindset about the purpose of blogging, ways to generate ideas, thinking about your audience, and how to drive your topic with a tightly focused long-tail keyword.

Stay tuned for part two of this series, where we’ll talk about another important aspect of how to write a technical blog post: improving your actual writing process itself. Until then, good luck and happy blogging!

This post originally appeared on The Quick Left Blog

Four Things Our Developers Wished They Knew On Their First Day

As part of our onboarding process at Quick Left, we meet with recent hires after 30 days and ask them several questions about their experience so far. One of the questions that gets some of the most interesting reponses is: “What advice would you give yourself on your first day?”

After six years in business, we’ve asked this question quite a few times. We recently took some time to read back and analyzing the responses we’ve gotten. When we looked closely, some trends started to emerge. Interested in finding out what it takes to be a software consultant? Read on to find out the top four pieces of advice our devs wished they had known on their first day.

Forget Imposter Syndrome

Becoming a tech consultant can be intimidating. It’s natural to feel like you don’t know enough to effectively counsel clients in making the best decisions. Our advice? Forget imposter syndrome.

As one developer put it, “you come in here more prepared than you think”. Everyone has life experience that they can bring to bear on the job. In the words of another QLer: “even junior developers have a lot to offer with their other experience”. We’ve hired people from all kinds of backgrounds, from the restaurant industry, to project management, to education, and every one of them has found that they have skills they can leverage in serving clients. “Just relax and know everything will be fine. You’ll learn things”.

If you just can’t shake the feeling of inadequacy, you can always fall back to this advice: “shut up about your lack of confidence, keep it to yourself”.

Be A Self-Starter

Quick Left has always been known as a democratic place to work. We made the WorldBlu List of Most Democratic Workplaces in 2012 and 2013. As we’ve grown, we’ve always managed to keep that spirit alive despite the pressures of scaling. One of the things that’s made that possible has been that we’ve focused on hiring people who know how to take the initiative.

Here’s some of the advice we’ve heard employees give about being a self-starter: “start working, don’t wait for someone to tell you what to do”. Another person said, “just try things and if something breaks, its not the end of the world”. Because we’re smart and know when to ask for help, we know that sometimes the best strategy is just to dive in and try to solve things.

If all else fails, you can always read the manual. It never hurts to read the docs. If that fails, there’s always “source code spelunking” (a favorite pasttime around here).One QLer reflected: “sometimes I was asking questions and the answer was right there in front of me and I just needed to read more”.

Get To Know Everyone

Two heads are better than one. And a whole team of heads is better than two! We pride ourselves on a strong culture of education and mentorship at Quick Left. We know that we can rely on each other to help when the going gets tough. None of that would be possible if we didn’t have great relationships within the team.

Although we host plenty of events that bring our developers together, like our hackfests and monthly happy hours, some of our developers found that they just had to get themselves out there and “engage with the team outside of work”.

Others reflected that they wished they’d leveraged the team as a resource earlier. So how do you get integrated? “Go out to coffee with everyone in the company”, one person suggested”. This goes for both the social and the code realm: “reach out and talk to my co-workers more. Both small talk and technical stuff”.

As nerds, it can be difficult to connect socially. But the benefits more than make up for the little bit of discomfort it costs up front. Tight teams stay together.

Don’t Sweat It

Finally, there’s one piece of advice that we saw again and again as we looked back through the archives: “don’t sweat the small stuff”. The first days on a new job are always a little bit nerve-wracking, but everything is going to be fine in the end.

Your team wants you to succeed. We’re all in this together. So don’t get caught up in little problems, because we’re all here to support each other in the big picture. One developer admitted: “it was stressful for me to get into a new focus. I would have told myself to calm down.

Displaying a little bit of confidence can go a long way. It can put clients, managers, and team mates at ease. This makes everything run a little bit more smoothly. Take another QLer’s advice: “just relax and know everything will be fine”.

Conclusion

There are a lot of things that go into being an effective developer. You have to know your tools, stay up to date on the latest technology, and make sure that you’ve thought through all of the edge cases. At the same time, being a consultant is no walk in the park either. You have to be able to balance budget, time constraints, client relationships, and getting work done. Between the two of them, what it takes to be a software consultant can seem daunting.

Even developers coming from a product background are sometimes daunted when they first become consultants. But after a few months, most of the people we hire tend to get the hang of it regardless of what they were doing before.

After doing this for several years, it’s interesting to look back and see that developers consistently gave the same answers for how to deal with filling this role. Time after time, the answer to the question “what advice would you give yourself on your first day” came out matching one of the same themes.

If you’re entering the world of software consulting, take these tips to heart. Believe in yourself, trust your gut, say hello, and just relax. Best of luck. See you on the interwebs!