Fluxus Frequency

How I Hacked The Mainframe

How to Choose the Right Tech Stack for Your App

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!

Why We Use Test-Driven Development (TDD)

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.

Five Hacks to Level Up Your Learning as a Developer

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!

How to Learn Best as a Developer

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!

How to Write a Technical Blog Post: Part 3

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:

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!

How to Write a Technical Blog Post: Part 2

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!

How to Write a Technical Blog Post: Part 1

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!

What It Takes to Be a Software Consultant

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!

Bring Back Your App: How to Prioritize Your Best Features

This post originally appeared on The Quick Left Blog

how to prioritize your best features

Introduction

The tech world moves fast. It’s not uncommon for a startup to scale from two people in a coworking space to a team of thirty or more in a matter of months. Just as often, the team shrinks again due to sudden market changes or errant developers moving on to the next big thing.

When you’re getting ready to rebuild your business, it can be hard to know where to begin. There are so many things to do, from marketing, to onboarding a new team, to deciding what to build next.

In part one of this series, we talked about some of things you can do on the technical side to get your dev team up and running with a minimum of fuss.

In this, the second and final part of this series, we’ll focus on how to prioritize your best features. We’ll look at how to decide what you should get rid of and what you should pull out into its own codebase. Then we’ll tackle the question: what to build next?

Finding Your Strategic Direction

Assuming your development team is all ready to go, you might start to ask yourself: “what do we build next?”

But before you assume that you’re ready to start prototyping and shipping new features, you should take a hard look at what’s already there. Then, ask yourself if you shouldn’t do a little housekeeping first.

Take An Inventory

It’s a good idea to take an inventory of the workflows and features that are already in your application. Make a list of ways that users interact with the system. You could even consider writing user stories for the functionality that’s already there.

Consider Removing Features

Here’s a fun exercise. Once you’ve created a list of your use cases, go through and assign a value to each based on how important you think it is to your users. Then check out your analytics tool and compare your assumptions to the actual engagement of each feature.

When you’ve completed this process, you can begin to reprioritize. Are there secondary features that aren’t seeing much traffic? Maybe they were failed attempts to grow your user base that you never got around to pulling out. Maybe there are features that used to be popular, but a competing technology rendered them obsolete. Can you identify any parts of the app that require a lot of upkeep, but aren’t really serving your users? Here’s the tough question: what can you remove?

Think about Basecamp. They used to be 37Signals, but in February 2014, they announced that they were dropping support for all of their applications aside from Basecamp. They whittled it down to what they knew was successful so that they could focus all of their resources on it.

You can do the same thing on a smaller scale. Focus on the part(s) of your application that made the business a success in the first place. Do your marketing and landing pages drive users to interact with that feature? Is it easy to get to? Is it easy to use? Are there other features or workflows that are getting in the way of users finding their way there?

If you can identify some features that you can lose, you can focus your resources on the things that bring users to your site. You free up energy to refine them and make sure they’re solid and bug-proof. It also gives you room to experiment with new secondary features without overwhelming your users. I know one company with a well-established product that follows this rule: “you can’t add a feature unless you remove one.”

Don’t build yet, even if you have customers clamoring for it. Remove the cruft first. Think of it as refactoring at an application level.

Consider Splitting Out Services

In part one of this series, we talked a bit about refactoring your application code. If you do a little bit of refactoring, and find yourself getting into this whole code extraction thing, maybe you want to go whole hog. Talk with your engineers about whether it makes sense to extract an entire part of your app into a separate service. Some good candidates include: exposing a REST API, creating a gem to talk to your API, storing data that’s shared with other applications, or integrating with an Elastic Search service.

In some cases, starting a whole new code base can take a lot of time, and might not be worth it. On the other hand, if it’s hard to make changes in the code you’ve already got, sometimes extracting a service can actually speed things up. With a smaller surface area, and code written by people who currently work for your company, it’s easier for folks to grok what’s going on. This leads to faster development.

If you do go down the road of extracting services, your team should take the time to define clear boundaries between the old app and the new one, and describe how they will interact in detail. For example, if you’re pulling out an API, you might want to come up with a sample JSON response and the HTTP Status Codes that will be used before you build it. Defining the limitations and structure beforehand can keep a project like this from dragging on endlessly.

Use MVP To Figure Out Where To Go Next

A lot of people don’t realize it, but a Minimum Viable Product (MVP) isn’t just the first version of the thing you’re building. It’s actually a process. A way of testing out the market to find out whether things you think that people will like are actually things that people will like.

If you haven’t tried driving your business this way, you should! Instead of just guessing what you should build next, or building whatever customers ask for, you can actually find out using research and numbers. Customer requests are great, but spiking on new features and getting information from analytics and customer feedback can really help you hit a home run.

Here’s basic gist of MVP. You start with an idea. It might be an app. It might be a feature. Either way, you build just enough to find out whether it makes sense to invest further in your idea. How do you find out? Measure user response with clicks and sign-ups that actually go nowhere, and use analytics, questionnaires, interviews, and emails. When you’ve got data, analyze it. Do they love it? Keep going! Was it a partial success? Ask yourself: what can I keep, what can I lose? Otherwise, pivot or abandon your idea. Build something else. Measure its success. Analyze your data. Repeat.

For a more specific walk-through of using MVP to drive your business direction, check out my Actually MVP post.

Assuming you’re getting ready to scale up your app, you probably already have some ideas about what you want to build. Stop for a second, and consider adding a couple of months of MVP-driven development to your roadmap instead.

Wrapping Up

In this post, we looked at ways to find your strategic direction when beginning work on a product that’s been on ice for a while. We talked about how to decide what to remove, what to extract, and what to build next. Hopefully, the process I’ve outlined here has got you thinking about how to prioritize your best features. Now, it’s up to you to build the next big thing. Best of luck!

Bring Back Your App: Ramping Up Developers on Code

This post originally appeared on The Quick Left Blog

Introduction

Remember the glory days? Your company had it all! New signups every day. Coverage on the hottest blogs. Money was rolling in hand over fist. All thanks to your hot app. You and your goons really nailed it when you followed an MVP process and built just the thing the market was looking for.

But then something happened. You shifted focus to integrating with another company’s API. Or you lost your entire developer team. Slowly, kudzu vines covered over what was once a glorious app. The technology you used to build grew outdated. Bugs accumulated, but there was no time to fix them. You shed a single tear when you thought back to the glory days.

Finally, a new day dawned! You got a funding round! You’ve just hired a new team of developers. They start next week. You can’t wait to get them slinging code. But are you ready? Starting a new team on an old app isn’t as easy as handing them laptops and saying “clone down the repo”. In this post, the first of a two-part series, we’ll take a look at some advice you can use when ramping up developers on code in a legacy application. When we’re through, you’ll be ready to let the good times roll again!

Have An Easy Setup Process

Getting developers set up on a project can be time-consuming. Maybe you’re planning to write off two days for each person to set up their laptop, get the application and its dependencies installed, and familiarize themselves with the codebase. If it’s just one or two developers, you can probably justify four days of lost time. But what if you’re bringing on a team of ten? And what if they could get set up in one day? Or even half a day? That would be 15 days spent on developing new features and bringing in more money!

So how can you get them up and running faster?

Documentation

Documentation is so important. I can’t possibly recommend it enough. As a consultant, it’s one of the first things I look for when checking out a new code base. Docs are the most efficient way to get a new team member up and running. If they’re up-to-date, new devs can read about the project architecture and setup process, instead of having one of your more experienced developers take the time to sit down and explain it.

There are many effective ways to make documentation accessible to your team. I’ve seen companies have success with their GitHub project wiki, Atlassian Confluence, a docs folder in their app repo, or a separate docs repo on GitHub.

Document as much as you can. Your main application should have a thorough README. It’s the first thing people will see when visit the GitHub repository. If you’re running separate server and front-end apps, there should be a way to understand what has to be done to get them to talk to each other in development. How do you install the dependencies? How do you run the tests?

Sometimes, project setup can get held up by weird system setup issues. Maybe the app used to run on a pre-Yosemite version of OS X, but when you try to install it on Yosemite, it runs into problems with Nokogiri. I recommend creating a troubleshooting document and putting errors and their fixes into it. At Quick Left, we cut our dev setup time by several hours when we introduced a troubleshooting doc in the Sprint.ly repo. It also allowed senior members of the team to stay focused, instead of context switching to help people.

Some other good things to document include: language style guides, office culture, PR templates, things to look for in PR review, QA tasks, and deploy steps.

Docker

We live in an exciting time. The dawn of containers has made it easier than ever to make sure that each person working on a project is working with the same system setup. I like to use Docker to facilitate running applications across all environments, from development to CI to production. If you’ve never created a container before, I recommend checking out my colleague Alex Johnson’s Sailing Past Dependency Hell With Docker.

Docker isn’t right for every team, but if you have the knowledge and time to get it set up, it can save hours of time that would otherwise be spent googling errors and entering arcane commands into SSH tunnels. I’d recommend looking into it.

Pay Off Technical Debt

Great documentation is a good first step, but often it isn’t enough to ramp up developers on code in a reasonable amount of time on its own. If your app has accrued significant amounts of technical debt, this can present a major milestone. There are two kinds of tech debt to look for: dependency debt and native debt. Here are some ways to pay down each.

Dependency Debt

If your app was built back in the heyday of (name your tech stack here), you probably made use of a lot of open source packages that were popular and well-maintained at the time. But fast-forward a few years, and suddenly some of your dependencies are outdated, others deprecated. This can be not only frustrating, but also a potential security concern.

If this describes you, you’ve probably missed some patches that deal with widely publicized security issues. This can be a concern for open source packages and languages alike. For example, if you’re still running Ruby 2.1.1, you might find that you’re vulnerable to DNS Hijack attacks and other security holes.

It’s safest to invest a couple of days getting your language and dependency versions updated before bringing on a bunch of new developers. Not only will this fix your security holes, it will save you tons of time in working out module version conflicts.

Gems & Modules

If your app is built in Ruby or JavaScript, you’re probably making use of Bundler or NPM to resolve dependency versions and pull them down. In your Gemfile or package.json, you may be specifying the specific versions of packages you want to use, like this:

1
2
3
4
5
6
gem 'rails',                  '~> 3.2.17'
gem 'jquery-rails',           '~> 2.1.3'
gem 'mysql2',                 '~> 0.3.11'
gem 'devise',                 '~> 2.2.0'
gem 'cancan',                 '~> 1.6.8'
gem 'nokogiri',               '~> 1.5.6'

Or this:

1
2
3
4
5
6
"dependencies": {
  "config": "^1.10.0",
  "hapi": "8.1.0",
  "hapi-auth-cookie": "^2.0.0",
  "superagent": "^1.2.0"
}

Your new developers pull down the repo, run bundle install or npm install, and soon find out that you actually can’t install some things on the latest version of OS X without passing special flags.

Or maybe you realize that the authentication gem you’re using is one or two major versions behind the latest release. Fine, you think, and update the version specification. But then, when you try to run the install, you have version conflicts with another gem.

I have yet to find a good way to resolve all of these problems at once. The best approach I’ve found is to start with the module that you most need to update. Bump its version, then try running the install. If there’s a dependency version conflict, change that. Keep following this pattern until the waterfall of pain subsides. Then repeat the process with the next package that you know needs updating. If you run into issues, sometimes a bundle update or deleting the node_modules folder completely and reinstalling can get you closer to success.

The Rails Upgrade By Version Trick

When it comes to updating Ruby gems, I’ve come across nothing more painful than updating Rails across multiple versions. I’ve recently been working on upgrading an old Rails 3.1 app to Rails 4.2 for a client. When I try updating the gem version all at once, I get so many regressions and new bugs that I don’t even know where to start.

There is a better way. Begin by upgrading Rails one minor version at a time. So, if you’re on 3.1, upgrade to 3.2 before attempting to go to 4.0. Then go on to 4.1 and 4.2. There’s a list of Rails releases you can use to drive this process. I’ve also found this Rails Upgrade Checklist site pretty helpful. It lets you know all the deprecations you need to change for each version along the way.

Native Debt

So you’ve got all of your dependencies updated, and installing your app is a breeze. You can get a new developer from zero to sixty in an hour. Great! But now, do they actually understand anything about what’s going on in the code base?

If you’re lucky, your last team wrote clear, understandable code with lots of comments and no duplication. In reality, the odds of that are pretty low. Because of customer demands and pressure on time and budget, every code base ends up with some cruft, duplication, and just plain cryptic parts.

Take the time before your new team rolls on to clean things up a little bit. It will be invaluable in getting them up and running, ready to be part of the conversation on architectural decisions. Here a couple of steps you can take to get there.

Refactor

You’ve heard it before: if you practice agile development, you need to refactor. It’s something you should be doing along the way if you’re practicing Test Driven Development. The mantra goes: red, green, REFACTOR. Nevertheless, there are probably dozens of places that your code could benefit from some refactoring.

If your team is new to refactoring, I highly recommend the Refactoring book or its Ruby counterpart. You don’t have to become refactoring experts, just pick up a couple of patterns and go to town. Most of the time, there is some kind of smell that’s repeated throughout the codebase. If you learn to identify it, it becomes easy to identify and snipe.

Generally speaking, I’ve found that the easiest wins are to extract and inline code. This works at any level of scope. If you have a big, unweildy method that’s doing a lot, you can extract a method from it. If you have a class calling a method that doesn’t make any sense, you might want to extract an object. You can also go the other way: if there’s some unnecessary indirection, you can pull code right into the class or method that needs it.

Spending a day or two refactoring the hairiest parts of you application can make things understandability. That makes a big difference in your team’s efficiency.

Delete Dead Code

Related to refactoring, another great way to reduce the mental overhead involved in starting with a new app is to remove dead code.

One easy win is to “snipe” unused dependencies. You should also look through the codebase and remove any functions or methods that are old and not being used anymore. It can be hard to determine where exactly those spots are. If you have someone who’s familiar with the code, asking them can be a good place to start.

My colleague Meeka Gayhart also suggests cleaning up cruft by looking for all the places where a package or method is called, and removing it if there aren’t any callers in the current code. You can also look through git history to confirm using the git pickaxe.

If you have a good test suite, make sure to run it often as you remove suspect bits of code to make sure nothing broke.

Take the time to clean up your code base before new developers roll on, it can save huge amounts of time. New devs don’t have to work as hard to understand what’s going on, so they can spend those mental cycles shipping new features instead.

Wrapping Up

In this post, we looked at a couple of strategies for getting a new team ready to develop on an old code base. We looked at how to streamline the technical set up process, some tips for updating dependencies, and ways to pay down technical debt.

There are few things more exciting to a major stakeholder in an application than seeing it rise from the ashes to conquer the world a second time. I hope these tips help get you back to the glory days! Stay tuned for part two of this series, where we’ll take a look at some higher-level planning ideas that can help ensure you make the most of your development time from here.