Scott Radcliff

Moving On

For the last few years I have been working as a sole developer inside a company. It has it's perks. No one can tell me my code sucks. No one will argue with my technical decisions. But it also has it's bad side too. No one will tell me my code sucks. No one will argue with my technical decisions.

Working by yourself wears you down pretty quick. You lose something. You almost need someone to question you. That alone forces you outside of your comfort zone and helps you grow.

I have been passively looking for a new place for a few years. What I really wanted was other people to work with. People that shared my family values, desire to build awesome software, and the best work environment I could find.

I came close, but nothing felt quite right.

I have finally found that company.

I will be joining the team at Whitelabel.

These are some of the most talented people I have ever been around and I am excited and grateful for the opportunity to be a part of their team. I cannot wait to get started and see what we can build together.

It Looks So Easy

"It's just a if/then/else, right?"

"Just put a link to create that report for me."

I could go on for hours. It's not entirely their fault. Software is incredibly complex, but looks easy. Communicating that it isn't as easy as it looks proves to be more difficult than it should.

Anthony Colangelo touches on why just is a bad word in software development. Definitely something every creative person has encountered. Especially when they make it look easy. And all the good ones make it look easy.

Nginx Load Balancing

Learn Code Academy has a great 7 minute video on load balancing a Node app using Vagrant.

Simple Wireframing Tool

I always forget the the URL of this awesome little wireframing web app. I don't wireframe often, but sometimes I need to communicate an idea more clearly than on paper.

Questioning Best Practices

Best practices are great. They allow us to use systems that those smarter than us have laid out because they have found that they work well.

But like anything else, best practices can get misunderstood. As they go from person to person, a little gets lost. By the time the get to, I don't know, say the 1000th person, they may have lost their meaning.

Why do you TDD?

Is it because you have found that this is the best way to build software?

Do you remember what it was like before you started using TDD?

What would happen if you built an entire application without TDD and then covered the parts that were the most important with tests after?

What about no tests at all?

Challenge yourself to think with individuality. Try new or old things and always question your conclusions.

Living Documentation

But code only tells you how things work. It doesn't tell you why they should work the way they do, or how they are actually supposed to work.

David Leal on Writing Living Documentation

Readme Driven Development Revisited

A couple of years ago, Tom Preston-Werner wrote a blog post about writing your README first. The basic premise was simple. Before you write any code, write down how it will work. Detail all of your documentation, and then once you have a solid understanding about how your library will work, you then drop back and write the code.

It was quite popular, and a lot of developers loved the article. It solved two problems. First, it provided a solid way to provide documentation for users of your library. Second, it provided an opportunity to find and think through possible solutions before they were programmed.

Tom stated that we missed something between waterfall and agile.

On the complete opposite side of this issue, Joel Spolsky wrote a blog post about creating highly detailed functional specs.

Joel stated that without all the details formally documented, a developer can't possibly know what to build. There are just too many questions that need to be answered, and these questions are easier to answer in a detailed text document.

Joel goes so far as to say that no code is written at Fog Creek Software without a spec.

I think there is some room between the two of these. There is a sweet spot between a README for a library and a fully detailed document for an application.

Functional Specs

Before I dive into what I think the sweet spot is, let's define what a functional spec is.

A functional spec is document that details all of the user flows of an software application. It goes way beyond just documenting how an app works. It goes into great detail about every possible item in the application. Generally, these documents have wireframes and screenshots of the user interface. A functional spec might go so far as to have personas and scenarios.

The knock on full fledged functional specs is that you can't possibly know everything up front. These specs are directly tied to waterfall. The idea is that a product manager creates these documents and "hands them over the wall" to the developers, who then strictly follow them.

The problem with this method is change. As developers learn about the application while developing it, it becomes difficult to add features based on new knowledge because the manager has spent several hours detailing everything.

Joel really goes into detail in his blog series. He makes some great points and has me about 80% convinced that these documents are quite useful.

My problem is that most of these specs go too far.


When Tom described the process of documenting your library or project with a README first, he referenced the fact that we lost something between functional specs and agile practices.

Tom targeted libraries and projects specifically, I tried it out and thought it was great, but I don't write a lot of libraries. I write lots of applications, and in a true agile mindset, documentation before code is evil. So I kinda forgot about it and moved on.

But these types of documents do work with software applications regardless of type. It's super helpful to think through views and features and document how all of that will work.

This leads right into TDD. Something gets lost with user stories. They typically lose context, even with the given when then syntax.

The Sweet Spot

Okay, so if we have these monster documents that are created in a word processor by some manager and then we have simple text files created by developers, where do they meet in the middle.

Well, the word spec has a bad connotation with it. Traditionalists think of these docs as final and agilists run from them like the plague.

What about guide? What if these docs were not final spec, but guides. Maybe these docs just state based on what we know right now, this is how the application will work. The guide then becomes more of a minimum set of features and screens. And it's easier to change a guide. No one feels bad about updating a simple guide that doesn't have three full days worth of work attached to it.

The Functional Guide

So, this is it. I think a Functional Guide is what serves me best. I can take everything from Readme Driven Development and some aspects from Functional Specs and create a hybrid.

The format depends on the audience. If it's developers, then it should absolutely be a README. If you use markdown, you can add images of wireframes, sketches, or whatever else you need to communicate. Plus, it's diffable in Git. You can update the doc as you build out new features and deploy the new README with the branch you are working on. It just becomes part of the refactoring process.

If your audience isn't developers, then maybe a formal document makes more sense. Something interchangeable, like a PDF. It becomes a little harder to track changes, but it's certainly possible.

In the end, this is really about thinking. Thinking about the users of the software. How will they interact? What is the best flow for them to complete a job? In fact, what jobs need to be done?

One last point. If you've ever been the newest team member, you'll know that it can be really difficult to get up to speed on a project. It would be incredibly useful to have a document that you could look through that detailed the thoughts behind some of the decisions that were made. Bonus points for being able to go through the history of that document.

And finally, I'm just finding what works for me. Maybe this is totally insane to you. I don't know. Maybe your brain is wired differently from mine. I know that when I sit and start typing out how an app should work, it opens a lot of door to ideas that I know I wouldn't have thought of before.

Give it a shot. See what you think.

I'd love to hear your thoughts on what works for you. If you don't mind, send me an email at and share your experience.

Coders And Programmers

I'm not sure where the conversation started this time, but it has come up again. Someone on the Internet assumes that being able to code is all there is to building apps. That as long as a person can code, that's all they need.

And in fact, they could just find anyone that knows how to code, tell them what to do, and off they go punching keys and writing code.

Obviously, nothing could be further from the truth. Programming is such a small piece of the puzzle.

Dave Winer took offense, and felt strongly enough to write on his blog about he felt.

Dave makes some really great points. I want to touch on a few of them.

An Immature Industry

Dave says that he is frustrated with the term coder because it seems to go over our head. That it misses some very important parts of our industry, noting leadership and developing new talent. He says that this is due to an immature industry.

I'm not sure I think it goes over our head. I think it's simply ignorance and a lack of effort to understand how software systems are built; web, mobile, or otherwise. To blanket us as coders simply gives someone that doesn't understand our industry and is too lazy to try a blanket term to use. I think this is because they don't understand. The equivalent of saying I'm not good with computers. Lack of effort.

Dave also jokes about calling a reporter a keypresser, making the comparison that minimizing the software industry down to someone sitting in a chair entering text into a text editor, is no different from saying a reporter just presses keys.

I agree with Dave, but I don't think this gets us anywhere. This just gives the other industry (the lazy one bundling us as coders) a reason to shrug us off.

But I don't know a better solution. I guess it's education. But that raises another problem. If someone is too lazy to bother researching how software is built, they surely won't bother reading or watching what we produce to help educate them. Although, it's probably still worthwhile.

Dave and I agree that developer is the best term. It fits what I do when building software. It's not just programming. It's thinking, designing (visually and architecturally), and then programming. To have an idea for something and take it from an initial thought to a finished product. Programming is such a small part of that.

The Art of Building Software

The problem I have with this programmer/coder talk is that it boils it down to a commodity. It's not longer a craft or an art. It's just an activity. I feel it attempts to reduce it to a statement like Take a few classes and you too can be a coder. It's easy.

I prefer the creator route. That's how I started. I didn't even know I wanted to be a developer. I just wanted to build stuff on the web and it just kinda grew organically with each step.

First Conference Talk Completed And Whats Next For Code Schools

Got The First One Done.

A lot of questions were floating around in my head as I gave my first conference talk about teaching programmers. Would anyone show? Does anyone care about my topic? How bad will I fail?

It was scary, but my expectations were just about where I wanted them. Actually, Self Conference was probably the perfect conference for me to cut my teeth on. Small enough to be semi-comfortable, but large enough to have plenty of strangers.

I presented on Teaching Programmers Through Empathy. Really I wished I would have called it Teaching Programmers Through Experience, but I still think it went rather well. If you attended, I would love to hear what you thought. Shoot me an email at and let me know what you liked and disliked.

Talks are great and all, but it's what happens after it's done that really matters. At the end of the talk, I took a few questions. To my surprise, there were about 5 people interested enough to ask questions. But that wasn't the coolest part. The coolest part was the dialogue. The attendees started to talk with each other and answer each other's questions with their own experiences.

This dialogue was especially sweet because it's part of what I presented on. Open dialogue and collaboration. I don't know if it's related, but I think I'll hold onto the thought that it was.

What I Learned

I was pretty worried about interest in learning how to teach programmers. I know code schools are doing well. And I know other forms of teaching like apprenticeships and bootcamps are also doing well. What I didn't know was if anyone is thinking about the environments these things are taught in. To take that further, I didn't know if anyone cared about what comes next.

I think we are ready for the next steps. I think more programmers are asking themselves what comes after code schools. Have code schools peaked? What else can we do? How can we make it better?

I'm looking forward to answering these questions and exploring options. With any luck, some conference will allow me to talk about what's next.

Speaking in Public is a Craft

You never forget how to speak in public, but you sure lose your mojo. When I taught a class every weeks, I was pretty good at speaking in front on people. Granted, it was a lot of the same people most of the time. But I got pretty comfortable and I even liked it a little.

I definitely lost that comfort. I'm looking to practice a lot more and see if I can grow speaking into something. It's definitely a challenge, and who doesn't like a challenge.

If you know of any speaking opportunities, I would love to chat. Shoot me an email at or reach out on Twitter at @scottradcliff

Teaching Programmers Through Empathy

I gave my first conference talk on May 30th at Self Conference. I presented on teaching programmers. I touched on four topics.

  • Safety. Creating a safe learning environment is huge. I went over what this means and some techniques to use.
  • Authority. Authority is all about becoming a reliable resource. I also touched on some techniques here.
  • Collaborative Learning. I probably spent the most time on this. It's so important.
  • Mentorship. I closed out talking about how you continue to teach after the course is over.

It went pretty well, and I think creating an effective environment for teaching is a great topic. Something we should definitely should be talking about more.

Remember , We Are All Educators