Navigate Here
Navigate Elsewhere
Monday
Jul062015

Version-controlling my dotfiles

tl;dr: There are lots of neat ways to version-control your dotfiles. I ended up with homeshick and myrepos.

Background

One of my goals for the last year has been to get more competent with my shell. I've used oh-my-zsh for years and found it helpful, but I'd never really bothered to learn shell-scripting or much about how my shell actually works. I've remedied that a bit (which I'll write about separately), and it's meant that my shell dotfiles have become a lot more useful to me.

Once I started to have a real investment of time in my shell and other command-line configs, I started wanting my usual tools -- version control, history, etc. I also wanted to be able to keep various computers in sync; I have a personal macbook where a lot of my configs originate, then my work computer, then various servers I log into to work periodically.

I'd gotten to a similar place a few years ago when I worked at US News, and I'd followed Brandon Rhodes's method for using git to track your dotfiles; however, my needs have changed, so I decided to see what other people do.

Goals

Since I'm doing a good bit of development at home and at work, and I want to share some settings but keep others private to their respective environments. Brandon's method of using a single git repo for all my dotfiles has a lot of benefits, but it doesn't lend itself to this particular setup; I want the work stuff in a private account and my personal stuff in my public github repo.

I also wanted to be able to maximize sharing, which means not requiring that a person take my whole setup to use part. For example, I found Byron Peebles's dotvim really helpful in starting to use vim, and I wanted to be able to share my various settings with colleagues and friends. However, I expect that not everyone is going to want to use my many idiosyncratic aliases and utilities. This means making my dotfiles modular, which is a little tricky --- it's not totally weird to want two separate repos that both end up putting files in .vim; however, doing that with git out of the box isn't really obvious.

For myself, I wanted a reasonably braindead way to bootstrap new machines and keep them in sync. It's not too unusual that I'll be doing a lot of work on a server for a few weeks and then stop touching it for months, only to login again and be frustrated that I've evolved how I work on my laptop and can't use similar shortcuts on the new box. Similarly, I tend to "clean home" every few months and then just work with what I've got for a while, touching-up the edges for a year or two before doing some serious remodeling. That means I need to be able to automate a lot of how my setup works so that it "just works" during the time I'm not focused on sharpening my tools.

The tricky part is that adding modularity makes the bootstraping/sync issue harder; I don't want to have to remember which 10 git repos to pulldown or update on a given box. I played a little with using submodules, but as always happens to me, I ended up making a little mess of my submodules within a few days; this reminded me that that tool doesn't mesh well with how I work.

Finally, because where I can, I try to use the most-specific tool to manage dependencies. For example, in a python project, you could use git submodules and shell scripts to manage all your dependencies, but pip has always been a lot less annoying for me. Similarly, vundle in git handles more than just checking-out and updating git plugins.

Where I ended up

It turns out, there are a ton of tools for managing your dotfiles, and github has even curated them. Initially, I was really interested in rcs and the python dotfiles package. But with rcs, my modularity goals were tricky to think through, and with the python package, given that I want all my python packages in virtualenvs, and part of that setup depends on my dotfiles, I decided to try to keep things simpler if I could.

I ended up using a set of shell scripts called homeshick to manage the dotfiles themsleves and myrepos to manage the many git repos. Homeshick handles symlinking files from a gitrepo into your home. It depends on bash, which means I can just clone it and be on my way. Symlinking has its own downsides, but the approach homeshick takes allows you to have a bunch of repos that all link into the same directories in your home, which solves my modularity problems. Then, myrepos handles cloning and bootstrapping the several repos where I keep things. I can have separate configs for myrepos for work and home (and even have one include the other), which is really useful.

I use these utilities to bootstrap tool-specific package managers, like zgen for manage zsh plugins or vundle for vim plugins.

What's cool

Now, I can run mr --trust-all bootstrap https://raw.githubusercontent.com/mattbowen/dotmyrepos/master/home/.mrconfig in my home and have all my basic tooling setup. Not only does this pull my personal tools, but also external dependencies like homeshick or spacemacs (which I've been playing with). Because myrepos is well-designed, at work I can have a .mrconfig that includes my home one and extends it. This allows for the sort of modularity and layering that I wanted.

I was able to pretty easily separate out my personal base setup from work-specific settings and keep all of this in sync. I can run homeshick pull and mr pull and have my tooling updated.

Also, with automated-setups, I'm starting to think about ways to make my own tooling more useful; for example, since I can create more "layers" of setup, I might want to break my .vimrc into some basic settings I want absolutely everywhere (like, even on my router), and then all the plugins I like using for programming and writing. I've got to think on this more though, since it will add complexity that I need to remember later.

What's uncool

First, I'm using many tools; maybe too many. The domain-specific plugin managers are useful since they usually do more than just manage git repos, but they also mean thinking about a bunch of tools in a specific order if I want to make sure I'm using the same vim plugins everywhere. This means it's not braindead enough yet; for example, if I've added some new zsh plugins, it's not always even obvious to me which tools I should run in which order to make sure they're updated in a given environment. I should be able to solve this with a shell-script or two, but I haven't done so yet (I didn't think of it until writing this, so +1 blogging I guess).

Having so many repos also makes sharing somehow harder; it's hard to point people to any one specific place if they want to use my tools. This blog post is in part to help with that, but I probably need to write another once my setup has settled down a little more to give a better overview.

Also, the homeshick approach of using symbolic links for everything means it can be hard to tell at a glance if I have untracked configs sitting around in my home. This is another thing that I can almost certainly fix with some shell scripting, but I haven't yet, and it's another place I can trip. Then there's all the problems that come with symbolic links generally; part of why I picked homeshick is that they have documented how to work around some of these problems, but just reading the docs should give you an idea of the woes you're headed for with the symlinking approach.

Finally, ironically, homeshick itself makes it slightly harder to share my configs, since homeshick requires that all the configs be in a REPO/home layout, which I don't think other people necessarily want. But, outside of work (where I don't think people will really mind), I don't really expect people to "fork" my dotfiles as much as copy them and use them for their own purposes, in which case, a slightly-weird directory-layout isn't so bad. And, on the positive, it makes it obvious where to put docs, if I ever write any.

What's next

Foremost, I need to just live with this for a few more weeks; I'm pretty happy with how things are working, but only time will tell whether the complexity is really worth it.

In the meantime, I want to smooth out some of the "what's uncool" — the biggest things are

  • making it easy to get an environment totally updated without having to run a ton of commands
  • being able to see which dotfiles aren't currently tracked somewhere
  • coming up with some sort of documentation for the various "castles" (homeshick's name for a set of tracked files) I have tracked

Resources and my repos

As I worked through this, I found the following really helpful:

I've got the following repos available for now:

  • .zsh -- zsh plugins and customization. This deserves its own blog post, because there's a fair bit of work in here.
  • .vim -- a (now pretty distant) fork of Byron Peebles's vim config, with about a million plugins, because I sure do like plugins
  • .myrepos -- the home of everything else
  • .git -- basic git configs and Tim Pope's automation for generating ctags

I still need to get my screen and tmux configs and a few others in, but they'll come before long.

Tuesday
Mar222011

Behind Every Website is a Hypothesis

Behind every website is a hypothesis about how to solve some problem people have. Being explicit about that yields benefits in clarity of thought, insights into process, and easier measurement.

In my last post, I talked a great deal about what an effective process for making a website looks like, describing a useful framework for approaching the complicated problem of making a large content site. I'd like to take a step back today, to thinking about why you might be creating a site in the first place.

Serious websites solve problems. If you're not solving a problem that real people have, you're wasting your time (and likely money). However, in my experience at least, people are not terribly explicit about what problems they are trying to solve. Behind every website, though, is some hypothesis (really a collection of hypotheses) about how the Web could be useful in solving some need real people have, and the site itself is an experiment testing that hypothesis. This applies to both content sites and web applications, although as usual I'll focus on content sites. Being explicit about the fact that you're making a hypothesis and conducting an experiment yields benefits in clarity of thought, insights into process, and easier measurement.

To give credit where it is due, the phrase "Web Design Is a Hypothesis" came from Alistair Croll and Sean Power in Complete Web Monitoring: Watching Your Visitors, Performance, Communities, and Competitors. Croll and Power focus mostly on local hypotheses — the idea that as designers work on specific pages and features, they should keep in mind that each decision they make is, at best, a guess as to what will work effectively for site visitors, and as such designers should plan to test their designs and refine them in the face of real world data. Later, reading Alan Cooper's "If users could lead innovation, they wouldn't be users," I came across his compelling analogy comparing web product designers to doctors, and realized that really, a website is a prescription to cure some diagnosed problem, and that web development is actually hypotheses all the way down, from the high-level product vision to the individual links on a page.

Your Site is an Experiment to Prove a Hypothesis, and That's the Way it Should Be

There are a lot of ways to conceive of a website. Typically, I see people think about it like a gadget — it's a cool thing like a kindle that will have a beautiful look, do some neat things, and reflect well on the people who guided its development. But that's not concrete enough. For content sites, the site is a vehicle for communication — more voice mail message than iPhone in the end.

There's a deeper level than just communication though — there's problem solving. You don't just communicate; that doesn't make any sense. You communicate to change the state of the world in some way. And if you want anyone to hear what you're communicating, you need them to have a reason to listen; you need to be helping them solve some problem, so that they can help you change the world the way you need it changed. So you make a hypothesis: if I develop a site that has « information, then «people will visit it and take « action and provide value « for us, because knowing «and doing « solves problem « for «. Then you can start pulling out things like beautiful design and fancy features, assuming that those things convey your information more effectively and allow the action to be taken more easily. But you need all those variables filled in — you need to know what people you're trying to reach, what information you have to offer them, what action you want them to take, and what problem they need to solve that your information helps them with. The goal here is to connect what real people need with what you have to offer. For web apps, this means some useful task that a computer can help people do. For content-centered sites, this means information that people need that you have a perspective on that you'd like to convey.

The greater the specificity with which you can fill in the blanks, the easier it will be to design an experiment to test your hypothesis, because your hypothesis will be more clear — and by "design an experiment," I mean "build a website." And using this way of thinking about your project will help guide the steps you take in executing it, helping you build better sites.

My Kingdom for an Example

For an example, I'll take my favorite fashion blog, I Found the Perfect (IFTP). IFTP takes on fashion like a design project, bringing to bear a formal creative process with tools like mood boards and careful resource planning to make expressing yourself through fashion easier for people who have an interest but not necessarily an inborn talent. Disclaimer: IFTP Is written by my lovely girlfriend, Laura, and I contribute photography and technical support — but I can talk about it without violating an NDA!

Although we weren't as explicit as I would be now, the site started with a couple hypotheses, one of which was

  • If Laura develops a site that «explains how to approach fashion problems like general design problems», then «women who are interested in fashion» will visit and «use the tools provided» and provide value «by helping us understand what tools are valuable to women who are interested in Fashion» because knowing «how to approach fashion problems like general design problems» and «using the tools provided» solves the problem of «the trouble of planning a personal "look"» for «women who are interested in fashion».

Now there's a higher level goal here — Laura wants to know which tools are actually valuable to women for other reasons, otherwise known as a "business goal." And that is again a hypothesis; Laura sees potential value in knowing which tools are valuable and understanding how to make it easier for other women to approach fashion, and whether she can really turn that knowledge into real value for herself will require other experiments and hypotheses. Because, as I said, it's hypotheses all the way down.

What if People Don't Realize They Have a Problem

It's possible that you want to solve a problem that either isn't top of mind for most people or that people don't even realize they have. I know when I first heard the concept of "wearable computers," I thought, "I don't want a stupid computer with me all the time; that sounds annoying." It took getting an iPod touch, which solved a specific set of computer problems well and was marketed to make clear what it could do for me; that convinced me that having a computer in my pocket was actually a great idea. Now, when my droid runs out of batteries, I feel hobbled without a wearable computer.

This is where tools like marketing and PR come in — sometimes, you need to make a case for the tools and information you're providing to convince people how you can help them. So, you end up making more hypotheses about how to convey the value of your site to people using the outreach you have available.

This is also a good signal to check yourself, though. First, if the problem you're trying to solve isn't obviously a problem or isn't one that many people care about solving, it means you're going to have more variables to understanding whether your site is working; you'll need to figure out how to measure your outreach efforts and then measure the performance of your site taking those outreach efforts into account. More importantly, you need to confirm that you're actually solving a problem and not just dreaming that lots of people have the same goals you do. If you think real people have problems like "they don't use my product" or "they don't visit my website," and that is the whole problem, then you're doing it wrong. Determining whether you're deceiving yourself about things that people need is complicated, though, and will have to wait for another post.

Working from a Hypothesis Motivates a More User-Centered Process

Stating your hypotheses explicitly shows that there are lot of variables in what you're doing. Once you realize you're solving a problem for some audience, you start to wonder "do they even have this problem?" Or, at least you do if you're me. You also might want to know what other, related problems they might have that you can help them solve. And then actually solving the problem well is going to require a good bit of work on its own — you need to be sure your site is actually usable by real people (not just you and your developers), that the information you're conveying is clearly articulated, etc.

This is where process comes in, and what motivates some of the steps in the process for developing a successful website that I described last time. A hypothesis is an educated guess; in this case, it's an educated guess about how I can solve some problem people having by creating a website. So, I want a well educated guess.

This desire to make a better educated guess makes me want to understand my audience better and focus my efforts on solving their problems; I know that's what I'm doing no matter what, so my process for creating the site should give me tools to understand my audience and validate my assumptions about what they need. I want to start learning about my audience so that I can understand how they understand the things my site will focus on. I want to know what tools they're currently using to solve the problems I'm interested in, to know with whom I'm competing, even indirectly. I want to use tools like usability testing to try to eliminate some of the variability in executing my site; I have enough to worry about with whether my my overall idea for the site is a good one.

Remembering my hypothesis also means that I realize, in the end, I am making an educated guess about what people will find useful. This means I'm going to need to (1) find some way to measure to know how good my guess was and (2) make changes to my site as after it's launched, because I'm going to learn things from my site's performance in the wild and therefore make better educated guesses in the future. First, this makes my analytics process a good bit more clear; if I'm thinking about my hypothesis at the outset, I'm less interested in vanity numbers like "visitors" and "pageviews" and more interested in how specific content is performing and how various segments of my audience are hearing about my site at all. This also means I want to find the easiest way to (in)validate my hypothesis that I can as early in the process as I can; tools like prototypes and generative user research become much more attractive when thinking about sites this way.

Realizing that the Hypothesis Matters Shows Process does not Ensure Quality

There's a flip side though. What really matters is the insight of your hypothesis and the strength of your execution. A good process can help you refine your hypothesis, and it can help hone your execution, but it cannot save you from a totally off-base hypothesis. It will, hopefully, help you identify where you're off base earlier and save you from sinking a lot of cost into a misguided "solution," but there's no guarantee. Poor execution can sink a good idea for a site, but great execution cannot save a site that doesn't solve a real problem. No amount of process can change that.

What's next?

Keeping the ideas from this post in mind can be useful for helping bring what you're trying to accomplish into sharper relief. I feel like the hypothesis template above ("If I develop a site that has...") could use some tightening though. There's also still the problem of figuring out how to detect when you're deceiving yourself about the reality or magnitude of the problem you're trying to solve. I'd love any suggestions on either of those topic in the comments.

Saturday
Mar052011

Making Websites

Starting a website with comps and code is a bad approach for content-centered sites. Instead, start by clarifying your goals and aligning your team around them, working to understand your audience, and honing your messaging to suit your audience and goals. From there, there’s a whole production process that should include content strategy and user experience design before you actually build a site. Read on to learn about the motivations behind this process or skip ahead to see my ideal process outlined.


I have been making websites since 1995 or ‘96. My family got its first computer in 1995, and once I got confident using it, I wanted to make things with it. I scraped together some money from cutting grass and got myself a QBasic book, and a few months later my parents got me an HTML 2 book (no tables for this guy) for Christmas. I’ve made websites ever since; back then, it was for fun; in college, it was for classes and occasionally for a favor; for the last six years, it’s been how I’ve earned my living (with the occasional favor still thrown in).

From the get-go, I’ve approached web projects from the perspective of a developer; the QBasic book did come first. I’ve always wanted to dive in and make something, because I love making things. Because I have brought a programmer’s perspective to projects, I’ve thought in terms of execution; when I hear an idea, it’s hard for me not to imagine how to make it concrete with code. This has typically been what people expect out of talking about a website — except maybe the designers who see images of the site’s interface instead of the logic and software stacks I imagine. But people who want a website are typically excited about it, and they want to see progress quickly, and so my approach has met their hopes well. The Internet still has a hint of glamour; to people I help, getting a new website is a creative expression (even when it’s for their business), and they are excited to see their expression live on the Internet for all to see.

Over the last few years though, an awareness has been growing inside of me about some deficiencies in my process. I’ve always been looking to solve computer problems, but I’m coming to think that what I actually need to solve are people problems. So, here, I’ve taken a closer look at a naive (and, I suspect, commonly used) process for making websites, and then I've outlined the improved process I’ve been refining for the last few years. In this post, I’m going to focus primarily on the problems of content-rich sites without ecommerce or advertising; the method described in this post should also apply to other types of sites, but my experience and passion primarily deals with content-rich sites (so more Wikipedia than Amazon).

A Rough, Suboptimal Process for Making Websites

Boiling it down, I think I can define the process I’ve encountered in the past into nine "easy" steps:

  1. Talk to your client to get a rough idea of what s/he wants; this “talking” could actually be reading an RFP, or it could be a sit-down meeting or two.
  2. Make some drawings of what the site could look like. If you’re feeling ambitious, the first set of these drawings will be called “wireframes.”
  3. Implement in code the drawings that the client liked. If the discussions from step (1) yielded any features that go beyond interface (e.g., some fancy search, a game, etc.), write those as best you understand them.
  4. Post the content that the client has written in MS Word to the website you coded.
  5. Have the client click around the site a little, get his/her blessing, and take it live.
  6. Send some reports to the client about how many people looked at the site.
  7. Post updated content you pull from MS Word files every so often; these might be on a schedule but are more likely driven by outside events and freetime.
  8. One day, field uncomfortable questions about why more people don’t come to the site and why the people who do come don’t stay.
  9. Redesign part or all of the site (you may or may not get to participate in this step). This is step typically not mentioned earlier in the process.

I realize this is a bit of a caricature, but I don’t feel like it’s terribly far off the mark; I've certainly worked on sites with more thoughtful processes, but I've definitely seen sites go live that start at (3) and stop at (5).

What Motivates this Process?

This process has a couple things going for it:

  • For the client, it makes spending feel more predictable — you expect that the web developers can give you an estimate for the cost at (1) and will do work up to that estimate in (2) to (5).
  • It gets the web team making things early; in projects I’ve worked on, there is nearly always substantial deadline pressure, and nothing makes you feel better about your deadline than having the comps and code.
  • For the client, it makes a messy, complicated process feel like buying a normal product, like a car.
  • It minimizes the number of meetings the client has to attend and therefore appears to reduce the work required of the client in producing the site.
  • On sites without a ton of content or very complicated features, it moves quickly enough that there’s good enthusiasm from everyone through launch.
  • For the client, it appears to contain post-launch costs — that is, until you see step 9.

I can see why these features are attractive. No one has unlimited resources, so of course clients want to know what they’re getting for how much. And web teams want satisfied clients and projects that they can deliver on time and under budget, so it makes sense that they want to dive right in and get the project dispatched. It assumes that you can know what will be effective at the outset, which is nice for all parties; the client feels like they've hired experts, and the site creators feel like they are experts.

HOWEVER, and there is always a however, there are some problems here, too.

The Trouble with the Existing Process

The trouble is that the process described above dives in to tackle the technology problems associated with a website without handling the really important part: it ignores the needs of actual people. People are complicated and hard to predict. And although clients are typically excited about their sites once they get them (I’ve been lucky to work with good designers and to be able to provide good technology), eventually they come to realize that they don’t really know whether what they've paid for is actually successful; do people find it useful? You see numbers of visitors, but it’s hard to tell if it’s a lot or a little — and even if you have benchmarks, the numbers still feel meaningless. You see “engagement” numbers about stay times and bounce rates, but they always feel too low and too high (respectively) — not that you can have a great sense of what the ideal would be. It’s hard to know whether the content you’ve provided is useful or whether people are even actually reading it.

The above process elides some useful tools that we have at our disposal if we so choose when creating a content-rich website:

  • Although professional expertise is brought to bear on the design and implementation of the site, the content of the site is left to people who are likely not web content experts.
  • Although the process brings in outsiders (assuming you bring in a design/development firm), no one actually talks to the target audiences for the site to see what they could use.
  • Measurement and analysis only enter the picture as an afterthought.
  • The process assumes that the goals for the site are made explicit upfront and does not offer support for turning desires into measurable outcomes.
  • The process assumes that the site will work correct at launch; there’s no structured plan for determining how the site should be tested and incrementally improved.

My Ideal Process for Making Sites

A picture is worth a thousand words (not that I won’t write another thousand after the picture)

My ideal web process

This process breaks into four major phases, and, importantly, it has a loop in it to imply that it is iterative:

  1. In the first phase (Inception, Audience Research, and Message Development), you figure out where you’re going, working to clarify your goals for the site and align your team to those goals (Inception), to figure out to whom you will be talking (Audience Research), and to express what you’re planning on saying (Message Development).
  2. In the second phase (Brainstorm Features, Content Strategy, and Outreach Strategy), you plan how you’re going to get there, putting together a picture of what exactly your new website needs to do to be able to reach your audience (Brainstorm Features), what content you’re planning to put on it and how you’re going to maintain that content over time (Content Strategy), and how your audience will learn about this content and contribute to it (Community and Outreach Strategy).
  3. In the third phase, you develop your first version of your website, starting with the navigation and interactive elements (User Experience Design), moving to the look and feel of the site (Visual Design), and then finally into the actual creation of code and copy in Production. Note that if you're doing things right, you're testing the outputs of this phase with real users to verify that you're making a product they can actually use.
  4. In the last phase, you analyze how you’ve done and look for insights for how to improve the site. Because analysis is an integral step and flows back into the others, you should have been planning for how to analyze your results in all the other phases so that your results here are more than just reports; they are actionable insights about what you need to improve on your site to meet your goals.
  5. From the analysis, you can brainstorm new features to make the site more effective, which will then change your content strategy and outreach strategy, which will then require you to modify your navigation and add or remove elements from the site, which means more design and then development to implement these changes. The process is inherently iterative, acknowledging that any website is at best a hypothesis about what an audience wants that can be improved through further analysis and refinement.

The diagram is of course an abstraction of a real process, and it disguises a lot of real complexity and fluidity in its neat boxes and arrows. For example, new ideas for features will emerge at each stage; content strategy, community strategy, and user experience design will happen almost concurrently and will often be hard to solidly differentiate; once production kicks off, it’ll likely run continuously for the life of the site, creating new features and content, modifying existing code and copy, or performing necessary maintenance. Additionally, it’s not like once you’ve done your audience research you’ll never return to it; however, I expect things will leach back into the audience research and messaging much more slowly than the rapid pace of iterations to improve the site.

That Looks More Complicated, What's It Get Me?

The big thing about this model is that it is goal and audience oriented; you start at inception by clarifying your goals and then dive directly into understanding your audience. The rest of the phases are basically about refining these understandings to reach your audience to realize your goals. These goals might be things like "teach people how to prevent crime" or "help activists promote my new program." The important thing is that you have a goal and then start breaking down the groups like "people" and "activists" into smaller groups that you can actually understand.

Additionally, the process proceeds to clarify the path from goals and audience to a site that you can measure and maintain. By including phases like content strategy, you will actually think in a structured way about what to include on your site and how to maintain it. And by thinking about outreach before the site is deployed, you can design your site to encourage outreach instead of figuring out how to retrofit it.

Finally, the process admits that what you create won't be perfect at launch. As Alistair Croll and Sean Power say, "Web design is a hypothesis." You will learn about your audience (and a bit about yourselves) after the site goes live; it is imperative that this real-world knowledge is analyzed and used to improve your site so that your site improves. It is wonderful to have experts writing your copy and developing your code; it's hard to imagine how you could turn insights into actions without professionals. HOWEVER, these professionals are going to be professionals in creating things for the web, not in your problem space or about your audience; you will learn with them what is actually effective in the real world by being a part of it with a live site that you monitor and analyze.

Ok, That Does Look Better, What’s Next?

Each of those boxes hides its own little process, full of work that needs to be done. Honestly, each box is its own discipline (yes, even inception, at least for some project managers). Additionally, thinking through many of these stages in terms of goals and eventual measurement is not natural for most people I meet; that’s where having people with experience running the show is really helpful. From these broad outlines, I’ve been working to develop a more detailed process for working your way from “I need a new site or to fix a really confusingly broken one” to “I have a vibrant, effective online communications program.” I look forward to sharing my approach as I refine it.


Friday
May282010

Working with Developers

If you have never developed software, the process can seem opaque and confusing. Understanding what motivates developers and what they sweat can help you achieve better results when you are collaborating with them.

Although I do a couple of different things at work, I spend the lion's share of my time as a web developer. I do not work at a software development company though, but instead as a part of a larger company that develops software to accomplish other ends. This means I regularly work with lots of people who have never developed software before (and maybe never wanted to). My goal here is to give non-developers a better sense of what developers do so that projects go more smoothly, cost less, and finish with higher quality. I feel like, for a person who has never written software, developers may be a little too mysterious, and so I hope to clear up some of the mystery here by explaining

  • what we love about developing software
  • what are a developer's inner conflicts that s/he is trying to balance against; these conflicts can tip your project from awesome to nightmare if not mitigated
  • what being a developer does to your brain; that is, where do developers fall down
  • what you can do to make your projects more successful when working with developers

Of course, I have a few caveats. This is heavily influenced by the specific setting of my work experience and the teams I've been on; I can't claim this post is universal. In writing this out, I've also come up with some improvements and projects for myself and my team, and in that respect, I recommend other developers try writing something similar up. Finally, as always, I speak only for myself here, and not for my employer or colleagues.

Why We Love Developing

Developing software is not like normal life activities; it allows you to translate your thoughts and needs into tangible devices that realize your intentions and solve your problems. Software developers, at least ones like me in small shops, are not disconnected from the product of their labor. In the software development classic The Myth of the Man-Month, Frederick P Brooks, Jr. explains

The programmer, like the poet, works only slightly removed from pure thought-stuff. He builds his castles in the air, from air, creating by exertion of the imagination. Few media of creation are so flexible, so easy to polish and rework, so readily capable of realizing grand conceptual structures. (Ch. 1)

And it is this, I think, that is so intoxicating. The day-to-day of software development is mentally taxing, often frustrating, and a little lonely. But the result is the ability to solve complicated problems almost out of thin air. Even better, the things we make are virtually tangible; we do not usually create processes and memos of understanding, but instead systems with interfaces and outputs that people actually interact with. Having a product that you can point to with capabilities that you can describe is strikingly satisfying.

Problem solving is important to the developers I know. We are not exactly artists (at least not all of us); we do not create things just to delight and evoke. We like to make things that make life easier, things that are used, things that people care about. We hate inefficiency and people doing tasks that machines can do, and we like making machines do repetitive tasks. We also like to learn something in the process; once you're hooked on developing software, there's a strong urge to get better at doing it (and to make it less frustrating, mentally taxing, and time consuming). 

What Are Developers' Inner Conflicts

Developers are, like all creative people, tormented by several sets of tradeoffs (or inner conflicts) and systemic problems in their craft. The most frustrating (and, paradoxically, enriching) can be pithily summarized:

  • Software is an asset, source code is a liability (thanks to Alan Cooper for the formulation)
  • Change is inevitable, and potentially very expensive
  • You have to use a computer to run a program
  • Adding people to a late project makes it later (Brooks's Law)

Software is an asset, source code is a liability

Developers work to create software. Software is the stuff you use on your computer: your web browser, word processor, favorite game, and websites like Twitter and Google. Software is clearly an asset; it makes your computer do valuable work and makes your life easier. To make software, we write source code (code for short) in a programming language, which is then translated eventually into software you can use. It's at this making software part that things go to hell.

The trouble is, every line of code we write is fraught with problems:

  • The more code, the more room for bugs; we translate fuzzy ideas into very concrete logic — sometimes, that logic is imperfect, especially when it is very complicated
  • The fastest, most secure code is the code you never wrote; the more complicated the code, the more room for performance and security problems
  • We're in our programs for the long hull — the amount of time we spend actually writing new code is small, compared to the time we spend maintaining existing programs; every new line is another line you need to understand 14 months from now
  • Writing code forces concrete decisions, many of which we make on the fly; every line is a potentially misunderstood intention, which we will later have to delete and rewrite
  • Code rots; we upgrade systems, add features, and fix bugs, any of which can break some older code that we haven't even touched

As such, we want the simplest design that will meet your needs. We love consistency; every special case means more code of questionable long-term value. (Special cases are the most expensive when someone is trying to understand code a few months or years later, or when we're trying to make a major change — like responding to a real-life customer need). When planning software, we want people to justify that the features they want will be used, because once we write the code, we have to live with how it affects the rest of our programs for as long as they're used. Worse, unused features can block us from quickly implementing new, actually useful ones.

Change is inevitable, and potentially very expensive

We know much of the code we initially write will be changed. We will imperfectly understand a client's requirements. The client will misunderstand much of his or her own needs until s/he sees them made concrete as software. The situation surrounding the software will change, requiring the software to pivot to meet reality. 

The trouble is, change is often expensive. There are two types of change: ones we planned for and ones we did not. With anticipated changes, we can typically make a change without disrupting the system; we've made ourselves places to configure the change, or ways to plug into the existing code without disrupting existing parts of the system. In unanticipated changes, most anything could happen — the change could be very simple, or it could require we rewrite 80% of the existing system.

DC Green SceneAn example could make this more concrete, using one of my favorite sites I've developed: DC Green Scene, a calendar of energy and environment events in DC. The calendar has a variety of filtering options, such as filtering by date, event type, and event topic. We anticipated the topics would evolve over time, and so we made it very simple to add new ones; adding and removing topics doesn't require a programmer. We actually capture a lot of information we could filter on (such as event location and cost), and adding these as options wouldn't be terribly complicated either.

However, imagine that we realized we were missing some critical variable in our filtering, such as the event size (to differentiate small meetings from conferences). This we did not anticipate, and it requires the following types of change (with the language required to make the change in parentheses):

  • Add the size field to the database, and figure out a way to add event-size data to the existing events in the database (SQL)
  • Add size filtering options to the code that actually executes the filters (Python)
  • Add the size information to the event's display on the homepage and on the event's page (HTML, CSS)
  • Add code to execute the size filtering dynamically (Javascript) 

So for this relatively simple change, we end up changing about seven files and using five different "languages." This doesn't count the design and usability work required to make the new feature work with the existing look. And that first change, where we need to collect new data about old events, is potentially a nightmare of busy work, or a confusing usability problem as we try to signal that size filter doesn't always work.

The natural question is, of course, why not make the system infinitely flexible, so that every change is simple? We certainly strive for simple, flexible systems, but often flexibility simply adds complexity to the code. A developer will sometimes say a system is over-engineering: this is when a system has been designed to be highly flexible in ways that no one will ever use. In such a system, simple tasks can become very complicated, because you use the same machinery for simple tasks as you would for very complex ones. Worse, you end up with lots of extra, unused code, which I'm sure you understand is undesirable after reading this far. 

Thankfully, there's a mitigation here: the earlier you realize you've made a mistake, the easier it is to fix the problem. When we first started writing DC Green Scene, we could easily add new fields to capture data and filter that data; there wasn't nearly as much code to upset at the beginning as there is now. Paying attention to mockups, prototypes, and early demos is essential; I know they usually look strange and it's hard to get past the interface, but seriously working with a prototype or half-functional product can save a ton of time down the road.

You have to use a computer to run a program

The essence of a developer's job is translate a human's ideas into instructions for a computer. Computers, however, are very unlike humans. Computers are terrible with assumptions. They cannot be given a vague picture of what you want with a little context and understand it. Everything must be described in minute detail. This means

  • every little detail requires a decision — what order things should be listed in, whether punctuation is bold or not, everything
  • when we tell the computer to do something stupid, it does exactly what we told it to

Sometimes, we use systems that provide functionality for us (e.g., when we use a content management system or some other customizable application). Unfortunately, this really just means that someone else made a lot of decisions for us, which might be great and might be totally wrong. In the end though, someone has to sweat the details, or they won't exist in the software at all.

Adding people to a late project makes it later

I used to hate estimating the timelines and costs of software projects. The trouble is, if you haven't written a type software before (e.g., someone asks you how long it would be to make a facebook competitor, but you've never written social networking software), it can be very tricky to have any clue where the pain points will be — and it's in the pain points that your project starts to slip. What always made this process more difficult is the realization that whatever we spec at the beginning will change, but deadlines typically won't.

The Scope CreepFrom the outside, both of these problems look like they could be solved by simply bringing in additional staff. If we get behind due to some unexpected technical trouble, or if the client realizes they need some difficult-to-implement realtime prediction system, we'll just bring in some freelancers. Unfortunately, adding additional developers to a late project will just make it later. The logic here is that once you have a substantial amount of code, it can take longer to bring someone up to speed than it would to implement that person's features. The problem is so well understood, it even has a name and a wikipedia entry: Brooks's Law

Brooks's law has implications: the initial team has a huge effect on the final delivery of the software, and new features added later in the development process likely mean the removal of some other, not-yet-implemented features. If the scope of a project expands substantially beyond its initial description, it will likely be impossible to meet the initial deadline.

A bonus conflict: Writing code requires a ton of focus

Finally, there's a problem that I couldn't pithily summarize but that feels too important to leave out: writing code requires an excess of focus. The number of things you have to remember to write a web application is absurd; I once read programming is the art of balancing an impossible number of details long enough to get an idea into your text editor.

Writing complicated code requires a specific state of mind akin to writing a flowing narrative; you need focus that excludes most everything else, and if someone breaks that focus, it can take hours to get it back. Paul Graham writes about the implications of the state of mind required to write code in Maker's Schedule, Manager's Schedule:

Most powerful people are on the manager's schedule. ... But there's another way of using time that's common among people who make things, like programmers and writers. They generally prefer to use time in units of half a day at least. You can't write or program well in units of an hour. That's barely enough time to get started.

This means many little interruptions through a day or meetings dotting the morning or afternoon can cause sizable delays by making it hard to get the necessary concentration to implement large features.

For my team, there are additional scheduling considerations: We divide all our work into two phases, development mode and deployment mode:

  • During the development cycle, we tend to work more slowly and carefully, while at the same time taking bigger risks with the code. These bigger risks mean that we can make bigger changes that are actually maintainable.
  • When we're in deployment mode, we expect we're going to be making our software available generally very soon; thus, we are looking to break as little as possible and work as quickly as possible — so we cut corners and add quick and dirty fixes, which we hope to resolve during the next development cycle.

The trouble comes in when we're in contant deployment mode (because the schedule was unrealistically agressive, the scope crept, or the content or approvals didn't land). When that happens, if we're rushing and just piling features in without adequate planning because deployment is "any minute now," we may end up making a mess of our own codebase, making later features much more expensive.  

Where We Fall Down

There are a few areas where I have noticed my developer friends and I fall down, I think likely by the nature of our jobs. As every developer is different, any one might be able to combat some of these deficiencies, but they're worth looking out for as a non-developer.

  • It's easy for us to get the "new/shiny's," wherein we find neat new technologies that solve some problem we've recently had; unfortunately, this is how a two person development team ends up with eight products written in six entirely different languages — making it very hard to staff properly in the future
  • We have trouble keeping the really big picture in mind; developing is a lot of very detailed work; unfortunately, that doesn't leave a ton of room for keeping the master plan in mind, which makes it progressively harder to give high level feedback on projects as we get into them
  • We can't know for sure if what we've made meets your needs; only you know what you really had in mind, which means your attention and testing are crucial for knowing whether we've correctly implemented a project.
  • The last 10% of any feature is hideously boring: it turns out that the last 10% of a feature is usually figuring out all the little ways that the other 90% break or are hard to understand, and so is really tedious, time consuming, really important — and we might need a little push to get through it.
  • We over-rely on technological solutions: I know I often assume that we need to automate some process that no one expects or even wants to be automated; I assume people should do as little work as possible, even if it's very time consuming (and thereby expensive) to get the computer to do some simple piece of person work. 

The valuable thing about realizing these weaknesses is that you can then combat them; knowing is, after all, half the battle. For example, at home I'm constantly playing with new applications, frameworks, and languages, but at work I'm pretty conservative about allowing new technologies into our stack; the more technologies you have to know, the less time you have to know any one of them well. 

What Can You Do To Help?

Armed with an understanding of what motivates developers, what makes them crazy, and where they're prone to weakness, you're hopefully brimming with productive changes you can make to improve the software products your company produces. Hopefully, you're thinking that going forward, you'll

  • think hard about what you want, finding good examples of similar products to clearly communicate your desires
  • think hard about the value of new features that you ask for during development, and think about which already-agreed-upon features you can live without to get your new features
  • sweat the details of projects together with your development team
  • pay close attention to prototypes and early demos to catch misunderstandings early
  • embrace technology — I'm not kidding; the more conversant you are with technology, the more likely you will be able to think about your problems in a concrete way that we can actually solve
  • remember that the most flexible system is not necessarily the best system
  • be realistic with your deadlines, knowing now that constant deployment leads to long-term panic 
Tuesday
May112010

Facebook Privacy

There's been a lot of chatter lately about Facebook's new privacy policy, especially about people deleting their accounts. Although the rules have changed, the decision about deleting your account is actually pretty simple.

I've seen a good deal of ranting about Facebook's new privacy changes. In particular, I see lots of people I respect talking about how they're considering deleting their Facebook profiles. I feel like there's not a ton to consider.

The decision: Is Facebook useful if all your data are public?

For me, that's what it comes down to: Is Facebook useful to you if you assume there are no privacy controls. There are lots of things I share without privacy settings: my blogs, my photos on flickr (almost all public, and nothing that would break my heart if a stranger saw it), my twitter account, etc. I get value out of having these resources online, and out of the networks around them.

With Facebook, the assumption about your content should be that it is public. The next question is, can you live with that? Can you keep what you share to be things that are only safe to have in public? Are there people on Facebook with whom you wouldn't communicate without it? Would that be a loss? Does interacting with those people require privacy? If you can still get value out of Facebook with everything being public, then stay. If not, stop using it; if you're not getting value, why would you keep using it anyway?

The rules have changed, the reality hasn't

Although Facebook has made it harder to control the privacy of your data on their network, I think it was insane to think anything that was there before was truly "private." We worked hard to drive this home to kids (and particularly teens) when I worked at McGruff, but perhaps we should have been targeting adults too. Realistically, you need to ask yourself, how careful are you with who you accept friend requests from? A few years ago, large companies started having interns from colleges friend recent recruits to get access to their profiles, and that was before the privacy changes. I know I've accepted friend requests from people I'm pretty sure I met at a conference or event. But I couldn't always tell you for sure who everyone with whom I'm "friends" on Facebook is. And those friends have access to my profile, my photos, and the things I post on Facebook.

The trouble has always been that interested parties could get access to a great deal of your profile data. I've certainly never considered it safe to consider what I post on Facebook truly private; I am typically much more concerned about a potential employer getting at my profile data than a company on Yelp anyway, and the chances that someone I'm friends with works at potential employer are pretty high. 

The risk for Facebook

I'm not claiming that Facebook will eventually turn our inboxes and private events into public feeds for anyone to see (at least not on purpose), but I wouldn't expect them to put worrying about the privacy of those data at the top of their concerns either. Their major concern is to leverage the social data they have about you to make your web experience more interesting, and then to leverage the same data to serve you better advertisements. Most of these privacy changes have been in the name of creating cool features to make a more interesting Facebook, not just to upset users. The risk is that that more interesting product is less valuable to users than being able to share their information in a privacy-controlled environment. My guess is features will beat privacy, and that the privacy-centered networks that people are talking about building will fail, but it will be interesting to see how it plays out.