I’m a planning whore. It’s true. I’m one of those weirdos that really enjoys creating data flows, use cases, wireframes, and functional requirements documents. My bizarre predalictions aside, wireframes are a critical part of planning any website or web based application.

Spending the time to plan your project out well at the very beginning may seem like a luxury your timeline and budget can’t allow, but most people realize pretty quickly that failing to do so often ends up costing exponentially more time and money towards the end of the project, when you have exactly none of either to spare.

Scope starts to creep, or features and interface challenges that hadn’t been thought through before are suddenly at the center of a series of critical and rushed decisions that have to be made. This means that you (and/or your crew) are stressed, and because you’ve run out of time and money, you end up having to cobble something together that works as a compromise, but doesn’t stand up to the caliber of work you pride yourself on creating.

For those of you who have been reading this blog for many years, you’ll recognize the tune I’m singing. I constantly harp about planning and documenting. My love affair with planning and documentation isn’t just because of that head injury I suffered as a kid – its because I’ve been fucked over so many times and on such a grand scale in the past when I (or my client/manager) have decided to cut corners and just “crank it out”. While the “crank it out” method may work sometimes, the times that it fails, it fails hard, at the expense of time, money, quality and developer sanity.

Okay, I’ll get off my soapbox. For now. </rant>

So, wireframes. I’ve done them in just about every application you can imagine. Visio, Smartdraw, Omnigraffle, even hand-drawn – you name it, I’ve probably tried it. I’ve been on the eternal quest for the perfect wireframing solution, but I’ve always been left wanting.

But What ARE Wireframes?

Wireframes are a graphical representation of a website or application that help illustrate the user interface without the clutter of stylized design elements. If you skip the wireframe process and go right to Photoshop comps, the client can often get so hung up on the fact that they want that button to be blue with rounded corners instead of green with a square corners that critical elements in the UI can be forgotten altogether. Wireframes let you plan through the user interface elements that are required for each screen in a barebones, no-frills manner.

I’m a big fan of sketchy wireframes, especially in the beginning of a project. I find that if you go to a client with something too polished, they perceive it as a structure that has been decided upon, even when that’s the furthest thing from the truth. The sketchy styled wireframes have a hand-drawn, loose feel to them that seems to better communicate that it’s a discussion, not a decision. By avoiding a polished, rigid wireframe, I have found that clients are more able to understand that what they’re looking at isn’t meant to represent the finished design.

I used to hand-draw my wireframes – but the obvious challenges there is that if a change is made to an element that appears on many pages of the site, you now have to re-do all of those drawings. Another disadvantage to pen and paper wireframes is that you have to write a crapload of code if you want to extend the drawing into an interactive format where the client can actually click on elements and see how they behave.

Evolution: Easy Prototyping

More recently, I had found a few apps that were a lot closer to what I was looking for. Balsamiq Mockups is a great application that has a gorgeous sketchy style and a great library of user-contributed downloadable interface elements, so just about every imaginable interface element is available for free download once you’ve purchased the product. More interestingly, Napkee is a commercial addon for Balsamiq that allows you to export your wireframes into HTML (with jQuery) or a Flex file, turning static wireframes into a prototyping tool with very little additional work. Neat!

Unfortunately, Napkee ended up being a little buggy sometimes, and perhaps more importantly, Balsamiq doesn’t natively support Master templates yet. So once again, when a change was made to the main site navigation, I’d have to go in and edit 30 files instead of being able to update a Master template and have those changes reflected across the boards.

Another drawback is that Balsamiq does not support the ability to switch back and forth from sketchy style to straight lines. In my workflow process, what I wanted was to be able to do the rough sketchy style wireframes in the beginning, update them as needed, and then be able to click a button and convert them into a more polished, final-looking set of wireframes that I could hand over to the graphic designers with a client sign-off.

A later contender, Flairbuilder, looked like it might be the answer. It does support the ability to toggle back and forth between sketchy and regular line styles, however the sketchy-style lines somehow didn’t look as nice as Balsamiq’s, and (this is the big one) in order to show the client a working prototype that was created with the desktop version, you had to export the file and then ask them to download a proprietary viewer. Fuck that noise. Half my clients are still on IE6 for chrissakes. I’m not asking them to download anything. So back to Balsamiq I went. Until now.

The Next Generation

Enter iPlotz. I like it already because the name makes me think of a pixelated rabbi pitching a fit. What are their next product lines going to be, the iKibitz and the iSchmaltz? HAH! I’m hilarious. But probably more importantly, it fills in the gaps that Balsamiq+Napkee and Flairbuilder couldn’t – and even adds some great project organization, management and collaboration tools in to boot.

The interface is pretty intuitive, and they have a nice library of elements from which to choose – plus, like Balsamiq, they have a public repository of snippets and projects available for download to fill in the gaps. Like Balsamiq, iPlotz has both a web-based version and a desktop version. The desktop version is a must-have for me, since I spend a hideous amount of time (4.5 hours a day) commuting through mountains where I have no connectivity.

What’s Awesome

• Works on PC, Mac and Linux. (I normally despise AIR applications – but it works here. Nicely executed.)
• Support for Master template files. If our main app nav or layout changes, change it once and it automagically updates on all the pages using that Master. HUGE time saver.
• Send work you created in desktop client to your web account, so you can do a lot of the work wherever you want and then upload it when you’re ready to use the collaboration tools.
• Toggle between sketchy-style, Mac skin and PC skin, great for rough mockups and then converting to polished final versions with just a click.
• Export PDF list with thumbnail of annotated elements an annotations, perfect for an organized breakdown of more specific details on each element. LOVE this – didn’t know I wanted this feature until I found it here.
• Online collaboration with others, allowing clients and co-workers to add notes and comments right into the file.
• Detailed version history.
• Built-in task management system with milestone, great for organizing work on large projects where tasks can get lost.
• Export wireframe pages as PNG.
• Share the HTML prototype on their server, or export to ZIP file and upload it to your own.
• One-click grid overlay.
• Easily embed the prototype in your own websites.
• Easily create or import additional UI elements from user contributed snippets.
• Properties menu lets you specify exact pixel dimensions for every element if needed.
• Separate menu of iPhone UI elements (Android coming soon).
• Automatic site map generation.

What Needs Work

Of course nothing is going to be perfect, and iPlotz is no exception. Here are a few of the things that bug me, none of which are even close to being deal-breakers in my world.

• Hotkey mapping is a little wonky in some browsers, but that is more an artifact of AIR/Flash than it is iPlotz, I think.
• Some elements do not maintain the same sketch style. For example, the module-style widget has rounded corners, which is inconsistent with the rest of the sketchy style’s squared corners. I also feel it is introduces a level of graphic design that I specifically wish to avoid by using sketchy frames. I have only noticed this on a handful of elements, however, and I spoke to iPlotz founder Mark Vernon today and he assures me that properties like that will be customizable in the near future.
• Element library isn’t as extensive as Balsamiq, but user-contributed snippets seem to be on the rise
• I didn’t see any way to save a frequently used imported snippet to your element library so you can get to the easily for future projects. UPDATE: Mark informed me that they’re going to be pushing out this functionality in one of their next releases. I’ll be checking it out on their staging server.

My Demo

In order to give it a fair review, I decided to whip up a small set of mockups, both to give me an idea of what the UI is like, and to be able to show you some “finished” products.

Below is the embeddable widget that I could easily stick into a branded HTML page to show my client. Click around in it, and you’ll see it’s fully functional. The size was dictated by my blog size, not a iPlotz limitation. You can display it at whatever size you’d like in your own sire.

Check out my sitemap demo version here. You can set your wireframes to public or private – I’ve got mine set to public so that you can see them, but I probably would keep them private and just assign roles to team members on a real project.

Take a few minutes and click around in the protoype. The nav menus, homepage accordian box, contact form, etc all work, and it required no extra work on my part other than to specify a link in the element’s properties. (If you’ve used Balsamiq+Napkee before, the process is basically identical.)

For client deliverables, in addition to the fancy shmancy working protoype, I can easily export single wireframes (using the sketchy style, the Mac OS style or the PC style):

Or I can export them all into one PDF [PDF link]. And this is my favorite part – the bit I didn’t realize I needed until I had it – I can generate a PDF that contains only the elements in the pages that have annotations [PDF link]. This is fantastic because it allows me to explain any special considerations around specific elements in great detail without cluttering up the wireframe itself. I normally have to manually create this documentation, so this feature alone has just saved me hours of repetitive work.

Another Potential Option. Sorta.

Another interesting contender is ProtoShare. It looks to have a lot of the same functionality as iPlotz, with online collaboration, version history, project management elements and easy prototyping, however their product is web-only, which I’m not crazy about, and their free demo required a credit card, which I can’t stand on principle.

Protip: The free trial is supposed to woo new clients and get them on-board and buying as quickly as possible – asking for a credit card number just so someone can try out your software is a little sleazy, as if you’re hoping I’m going to forget to cancel and you can suck me for at least a few bucks before I get around to it. If your product is good and brings value, I will buy it. Don’t force me. Dick.

For me, web collaboration might work fine for my personal web clients, but some of the clients we have at the agency I work for have strict rules about online collaboration in apps that do not live on our server or theirs, so my particular circumstance might limit the times I can use the collaboration in a practical situation.

The price points on ProtoShare is also a little higher. iPlotz starts at exactly free, albeit with a very limited plan, only 1 project, max 5 pages. The next plan is $15 a month (although the best value seems to be the yearly plan of $99 which comes with a license for the desktop version), whereas ProtoShare starts at $29/month with restrictions on how many people can review/collaborate. Who knows – it might be worth the extra scratch, but I hate using web-only tools, and I’m not going to give them my credit card information just to try out a demo. You can compare their prices in more detail here: ProtoShare vs iPlotz. When they come out with a desktop version, I might be willing to check it out. I don’t see any option for the sketchy-style mockups in ProtoShare either though, which is another negative in their column.

But hey, don’t take my word for it – check out the video demos on both sites and download iPlotz. I’m curious to know what you think.

Note: The title of this article refers to “cheap”. While to many people, “cheap” might mean “free”, I consider ~$99 a year a reasonable price for such a flexible tool that is such an important part of my job, especially since Balsamiq is $79 and Napkee is $49, so you’re spending that much even if you go the “cheaper” route. Seriously, you spend more than $100 on Starbucks (or whatever corporate coffee swill you’re into) a month, and I spend more than that on hookers and blow in a single week. You can also buy the iPlotz software outright without the web collaboration, which ends up being about $80 for a one-time purchase.

So that’s iPlotz. I’m a now paid member, and I’m very happy with what they provide. Plus, in talking to Mark today, it sounds like they’ve got more very cool features coming down the line soon.

What prototyping/wireframing tool do you use? Let me know in the comments!

Possibly related posts:

1. Cheap or Free Website Status Monitoring Its a call you never, ever want to get. “My...
2. Generate lists of banned words for forums and other applications If you develop software for a living, or if you...
3. Extending Facebook Static FBML Tabs with Dynamic Content This tutorial walks you through how to use DynamicFBML to...

I had the opportunity this week to go out to Redmond, Washington to attend the Microsoft Web Developer’s Summit at the MS headquarters. For this summit, about 25 leaders in the PHP (and PHP project) community were invited out to sit down with members of the MS product development teams and provide critical, honest feedback about Microsoft.

Background

The MSWDS is one of only four significant annual events within the PHP community (others include tek, DPC and ZendCon), and this summit is a bit harder to get invited to. Unlike most other conferences, where all you need is the cash to pony up for a conference pass and a hotel room to crash in, invites are very limited and attendees are selected because they have had some interaction with the folks at Microsoft, and are believed to be leaders and influencers within the open source community. To be blunt, these summits cost Microsoft a lot of money, so they need to make sure they’re getting the best bang for their buck.

Keeping that in mind, it would be easy to assume that we were being brought out there so that Microsoft could pitch us on the latest and greatest Microsoft products, trying to get the movers and shakers of open source to drink the corporate kool-aid and switch to Microsoft products. While more acceptance of Microsoft products within the open source community is obviously a goal, they are making a concerted effort to learn from us – what we need, where they are falling short, and how we can move forward together.

Discussions and Format

The summit itself was a total of three days, with the last day being optional for those open source developers who were willing to sign an NDA to discuss some of Microsoft’s emerging technology. During the three days, different representatives from Microsoft’s product teams sat down with us and asked for our comments, thoughts and ideas about where they’re at, and where we think they should be going. We met with folks from the IIS Web Platform team, the SQL server team, as well as some representatives from Codeplex, Silverlight, Powershell, ASP.NET Ajax (which is not exclusive to ASP.NET, despite the name), and Bing maps.

We had a chance to air grievances, which was cathartic in some ways, but I think it was more important to us to be able to sit down with the actual teams who are working on this technology at Microsoft, and really get into the specific challenges we face. The approach was not generally pitchy, and with very few exceptions, a great deal of effort was put into making all of us from the open source community feel like respected authorities in our field whose opinions really matter.

Something they did this year which was apparently not done last year was to include representatives from well-known PHP-based projects who are not normally parts of the PHP community. I honestly hadn’t realized that the many of the folks over Joomla, WordPress and Drupal often don’t consider themselves as part of the greater PHP community, and getting a chance to discuss that with them brought up some interesting perspectives. I don’t think the guys representing these projects were there in an official capacity, but their point of view was one that had honestly not occurred to me before, so that was a really interesting and unexpected benefit. There was some debate on whether or not these types of projects should be a more involved part of the PHP community, with good points on both sides, but I think most walked away with some ideas on how to move forward in making those lines of communication more accessible and open.

My Perspective

Of course the ultimate question from Microsoft was “What would it take for you to switch to Microsoft products for your clients?” My smartass remark was, of course “A fucking miracle.” But everyone in the room knew I was joking. I hope. If we weren’t willing to work with Microsoft on improving their products to work with open source better, we wouldn’t have been there.

As often as Microsoft has been an easy target in the past, and as much bad blood as there may have been in the past, there are people at Microsoft that care about working with the open source community, and who are making progress to get there. It is our job as technology professionals to fairly evaluate technology and make recommendations based on what makes the most sense technologically and financially. It is NOT our job to make religious decisions based on zealotry.

That means that if and when Microsoft can meet my needs and/or the needs of my clients, it can and should be part of that evaluation or I’m not doing my job. Does that mean I’m ready to switch back? No. Not yet, anyway. But I believe they are listening, and I saw some things during this summit that make me far more likely to start including some parts of Microsoft’s products into the technology I suggest as being potentially viable for client projects, which is a far cry closer than I was last week. Specifically, some of the stuff I learned about Silverlight, Bing’s geolocation products and Windows Azure (Microsoft’s cloud hosting platform) was pretty impressive. As I get to play with these products a little more, I’ll be blogging about them with my fair evaluation of pros and cons, so stay tuned.

I’m also excited to see where the Microsoft Web Platform Installer product heads. Right now, the WebPI product is a very easy to use, slick solution for the less techy individual who wants to, for example, deploy a WordPress blog in 5 minutes or less and may not have the savvy to do the install themselves – basically a MS version of Cpanel/Fantastico, which we have had available to us as web administrators for over a decade. That product is less interesting to me right now, but some of the directions they could go in for more advanced users like us hold real potential. We had some suggestions that were well-received, and if they are actually implemented in the way I envision them, it could honestly turn the table and make some of the Microsoft web server products something that I could consider recommending, or even using myself. (I should also mention that Cpanel is the most horrific, insecure, hack-prone web control panel I’ve ever used, and I am NOT endorsing it as a solution.)

The reality is that competition inspires innovation, and Microsoft getting better means progress for everyone. I saw a post on Twitter that basically implied that open source representatives attending this conference were traitors or sellouts. I don’t see it that way at all. We have amazing open source products like Firefox because the open source community worked together to create a better product, and Microsoft responded by making vast improvements to Internet Explorer, building in more security and standards compliance. When we work together to innovate, everybody wins.

Another transition I’ve been seeing in Microsoft which was really made more obvious by this summit is that there is a less omnipresent feeling of “all or nothing” within many Microsoft departments. As open source advocates, we enjoy having choices. Previously with Microsoft, you’d get the most benefit from their products by committing to an entirely Microsoft development process (“drinking all of the kool-aid, since the best stuff is the sugary goop at the bottom”), with benefits sharply falling off if you opted to pick and choose. This philosophy has always been distinctly in opposition with the open source philosophy, and I believe was likely the cause for some of the distrust coming from the open source community. Seeing this transition into a paradigm of being able to cherry-pick what we like for some things and sticking with open source solutions we like better for others is a step in the right direction, in my opinion.

An additional unexpected benefit to sitting down with all these MS product people was that I got a chance to better understand some of the legal/licensing challenges Microsoft faces. I’m not making excuses for them, but I hadn’t considered some of the obstacles in the way of people at MS who care about working with us. Microsoft is a big target with deep pockets, and they have to cover their own asses. I was quicker to dismiss some of the corporate decisions as being “evil” prior to sitting down with some of them and understanding why they do what they do. Don’t get me wrong – some of their decisions (*cough*sudo*cough*) still don’t make sense to me and I believe they are wrong, but I think I have a better understanding of where they sit than I did before

Wrapping Up

Overall, I would consider this summit a great success, and I hope I get to participate again in the future. There are several people who really deserve a shout-out for all of the hard work that went into this and are directly responsible for it’s success. From the PHP community, Cal Evans was a co-host and an absolute rock star, always quick to make sure things ran smoothly and kick-start conversations and redirect us back when we went off on tangents. From Microsoft, Karri Dunn, Tonya Young, Josh Holmes, Peter Laudati, Lauren Cooney, and others were amazing. I may be forgetting a few – I am still a little wiped from the week and the traveling.

Was this an instant fix? Certainly not. Do we all have a lot more work to do before we’re “there”? Absolutely. But as Cal Evans put it on his own blog roundup, “The more people I get to know at Microsoft, the less I’m able to despise the company.” They took the time to find out what we think, even when it may not have been what they wanted to hear. Time will tell whether or not they actually act on it.

Other PHP Representatives Blog Post Roundups

I’ll be updating this list as more people finish their blog post roundups, so you can get take their on the summit. Many of them are far smarter than I am, so it’s worth reading what they have to say.

• Cal Evans (@CalEvans)
• Chris Cornutt (@enygma)
• Maarten Balliauw (@maartenballiauw)
• Rafael Dohms (@rdohms)
• Keith Casey (@CaseySoftware)
• Romain Bourdon (in French) (@le_vrai_roms)
• Marco Tabini (@mtabini)
• Sam Moffatt (@Pasamio)
• Helgi Þormar Þorbjörnsson (@h)

MS Representative Blogs

If you’d like to see more about the fabulous people at MS who are working hard to move the company forward in a way that works with open source, check out their blogs. I’m proud to call these guys friends, and as long as we continue to have people like this working for Microsoft, I think the lines of communication and cooperation between both sides of the aisle will keep moving forward.

• Dave Bost (@DaveBost) – Developer Evangelist
• Josh Holmes (@JoshHolmes) – UX Architect Evangelist
• Tobin Titus (@tobint) – MSDN Site Manager
• Peter Laudati (@jrzyshr) – Developer Evangelist
• Mark Brown (@MarkJBrown) – Product Manager for Microsoft Web Platform
• William Coleman (@will_coleman) – Developer Evangelist
• Lauren Cooney (@lcooney) – GPM for Web Platforms at Microsoft
• Jas Sandhu (@jassand) – Interop Strategy Evangelist
• Ruslan Yakushev (@ruslany) – Program Manager on IIS team in charge of FastCGI and PHP support
• Scott Hanselman (@shanselman) – Principal Program Manager Lead

Funnily, as I’m writing this, Futurama: Into the Wild Green Yonder has been on television, and the scene that just played is the one where Calculon says “I’d like to thank the academy, my agent, and most of all my operating system – Windows 7, for everything it –” at which point his OS locks up. Windows 7 is actually a great product, and I run it on my Mac using Bootcamp and VM Fusion, but I thought the timing was amusing.

Kool-aid photo taken in Belize by me – just thought it was funny. Lead post image by Eli White.

Possibly related posts:

1. Final Fail of the Year This is just a quickie to let you know that...
2. Trying out Facebook Connect After much deliberation, I have decided to give Facebook Connect...
3. Identify and Fix SQL Injection Vulnerabilities in Web Applications Scrawlr is a free software for scanning SQL injection vulnerabilities...

In part one of this series, you learned what Subversion is and how it can help you, in addition to the terms you’ll need to become familiar with in order to use Subversion in your development process. Part two of this series goes into more specific detail about potential development environments that may work for you.

Subversion creates a bunch of hidden files and folders inside of every directory in your Working Copy that’s checked into SVN. If your Working Copy is on your local computer, you’ll see these as .svn directories if your system preferences allow you to see hidden files and folders. You don’t need to worry about these, and you never really need to look at them, but as a result, it is not recommended that your Working Copy be on your live production box. If you decide not to listen to me, you should at least consider adding a few lines to your .htaccess to deny prying eyes access to your .svn directories.

Working Copy & Repository on your local machine

Create a Working Copy on your local machine, create the Repository on your local machine, and FTP/SFTP the files once they’re committed. This will really only work if you are the only developer, or your local machine is the only machine changing files. (Okay, that’s not entirely true – you can set up the Repository on a network drive and have multiple developers Check Out their own Working Copies to their own computers, but I have run into issues running Subversion over a network.)

If you’re running OSX on your local machine, see this tutorial on WikiHow on how to set up Subversion locally. If you’re running Windows, there is an exceptional walkthrough on The WebSqueeze written by Christopher Hyne that is a must-read. Setting up Subversion on Mac or PC is really quite painless, and this is a perfectly valid way to go.

Pros: Easy, local setup. No external services to set up, your workflow doesn’t change that much, and you don’t need an internet connection to commit things to your repository.

Cons: Possible challenges with running Subversion over a network, you still have to upload your files manually, and you don’t get the benefit of a slick gui with which to view revision history, as you would using Beanstalk or Unfuddle for hosted solutions, or by setting up Trac (a gui reporting interface/wiki/ticket system) on your server. You can set up Trac on your local machine with Python and some extra work, but that’s always been too much trouble for me. Just MHO though – it works great for some people.

Working Copy on your local machine, remote Repository

For my personal stuff, since I use Mosso as my web host, which does not currently provide Subversion (though I hear they’re working on it), I use a third party Subversion host, like Beanstalk or Unfuddle. I create my Repository on Beanstalk or Unfuddle, Import whatever files I may have created for the project already, Check Out a Working Copy to my laptop, and I’m all set. I work on files on my laptop, test them on my local installation of Apache/PHP using XAMPP, Commit them to Beanstalk or Unfuddle (depending which service I’m using to host my Repository), and upload them via FTP/SFTP to the development server area.

The result is a little extra work – I have to deal with SVN on top of FTP/SFTP, but the security of knowing my ass is covered and I have a detailed revision history makes it entirely worth it to me.

One benefit to using a third-party SVN host, such as Beanstalk or Unfuddle (besides the fact that it gives you SVN capabilities if your server doesn’t support it) is that you get a shmancy web interface with which to view your revisions. Below is a screenshot of the Unfuddle web interface. You can see that it gives me a nice, organized view of all of the history, including revisions messages, numbers and person committing. (This is a project for JPM Morgan that I worked on with my friend Vidyut Luther.)

In getting Vidyut’s blog url, I see his latest blog posts states that he can, in fact, use Subversion on Mosso, by using Expandrive. I haven’t tried it yet, and he has, so if you’re interested in exploring that as an option, check out his blog post about it. I may give it a shot at some point, but I do like the simplicity of working with a third-party SVN host. I don’t have to administer anything, just create the Repository and go.

Remote Branches on dev, remote Repository, rsync to live

One way of handling your development environment is to set up a Repository on the remote server, Check Out a Working Copy on a dev area on the remote server, such as dev.example.com, and set up individual Branches for each developer. An SVN Branch is simply a copy of the filesystem separate from the main version, called the Trunk. Using Branches allows you to save your half-broken work frequently without interfering with others, yet you can still selectively share information with your collaborators.

In this scenario, no one ever touches the live files directly, ever. Ever ever. Everything gets pushed to dev for review, and once it’s approved, you run the rsync script and rsync is the only utility that ever moves stuff over to live.  It may sound confusing, but check out this simple blog post that explains how it can be done.

This can be daunting to set up, since there will be directories on live you may want to skip during the rsync (uploaded images, cache files, etc), but once it’s set up, it generally works like a charm, and it insures that no one ever screws up the live server, since no one is ever touching the live server.

Creating Branches is incredibly easy – check out the section on Branches in the free Version Control with Subversion book. They cover this concept and process very well. To give you an idea of what Branches look like, we’ll use their example structure, with a project named calc. This is what the original directory structure looks like:

You can see in this example, the ‘branches’ directory is currently empty, since we haven’t created any branches yet. The three file icons represent the total files in the project, which live in the Trunk.

Once we create a Branch, named ‘my calc branch’ (since it’s a Branch within the ‘calc’ project), you can see that a new directory is shown in the ‘branches’ directory, and a copy of the files from the Trunk live there:

Parts of each Branch can be selectively merged into the Trunk, so each developer can work on their tasks within their own Branch, break (and hopefully fix) as many things as they need to, Committing their work as they go, without affecting the main Trunk until the revisions are merged.

If you didn’t want to use Branches, you could add a staging server in this process. At a place I used to work, we had a development version that was actively worked on, a staging server, and a live server. We would Commit changes to the development server, rsync over to the staging server, and the staging server would automagically rsync every 10 minutes to live. Nothing was synced to staging unless we had kicked the tires and done QA on it on the development box, and if we couldn’t wait the 10 minutes, we could do a manual push to live by running the rsync script directly from the command line.

These are just a few of the possibilities. How are you using Subversion? Leave your configuration in the comments! And keep your eyes out for the next section that deals with the basic Subversion commands you’ll need to get started and optional gui applications you can use to make your Subversion experience easier.

Possibly related posts:

1. Getting Started with Subversion As a web developer, hopefully you’re already using subversion, and...
2. Dropbox versus FolderShare for Syncing Files Between Computers In my eternal quest to sync up all of the...
3. Questions to Ask Before Starting a Project We’re all human, and we all make mistakes and overlook...

As a web developer, hopefully you’re already using subversion, and this tutorial is utterly useless to you. If so, good job, and carry on! If you’re a web developer (or web designer, or web programmer, or are in any way creating files that display or do something on the internet) and you’re not using subversion (or any other version control), this tutorial is for you.

Since this is a question that comes up a lot, I’ve scoured the web for a really basic subversion primer, and although many come close (including the outstanding free online book, Version Control with Subversion), some people may feel overwhelmed at such an immense amount of information. Truly, I believe the only flaw in the Version Control with Subversion book is that they don’t include any real life set-up examples when discussing the Subversion Architecture.

There are many different ways you can set up your development environment, so I can understand why they would be hesitant to give specific examples, however some people learn best by seeing examples that relate to their lives, so that’s what I’m going to attempt to do.

The example set-up we’ll be looking at is one in which the developer is currently working either locally or remotely, and using FTP/SFTP to move files to the remote development environment webserver. For example, you either:

• Have a copy of Apache running on your desktop/laptop computer. You store and work on the files on your desktop/laptop, test them locally, and then upload them to your server  - or you -
• Make changes to the files locally on your desktop/laptop and test directly in the development space of the webserver (no local webserver) - or you -
• Use a text editor that allows you to pull files from FTP directly. You open them from FTP, make your changes, and save to FTP (no local copy stored at all)

I should mention that the third option here is absolutely the least recommended, especially since you’re not using version control. If your FTP process konks out mid-way through and the file isn’t saved completely, closing your application could mean losing that file forever. (Yeah, I’m looking at you, UltraEdit.) Regardless, if you’re using any of the above scenarios, or something fairly similar, this is aimed at you.

Because the Version Control with Subversion book is so good at explaining so much of this, I’ll be linking to it liberally, and just filing in the blanks where some people may get a little lost.

Disclaimer: This article is a very basic overview of subversion. There are many ways you might have your system and repository set up, and I won’t try to list them all, or even most. I’m going to use what many web developers would consider a “real world” example. You will not walk away from this a subversion guru, or able to deftly administer a subversion server. You will hopefully walk away knowing how to set up a simple repository, connect to it, and begin using svn in your day to day development. If you fuck something up, it is not my fault. Start on a test environment until you get your svn legs and feel pretty comfortable with basic commands.

This article is not a replacement for Version Control with Subversion – more of a supplement for newbies. As you begin to delve further into using subversion, that book will become your bible.

What is Subversion?

According to the Version Control with Subversion book:

Subversion (SVN) is a free/open-source version control system. That is, Subversion manages files and directories, and the changes made to them, over time. This allows you to recover older versions of your data, or examine the history of how your data changed.

Subversion can operate across networks, which allows it to be used by people on different computers. At some level, the ability for various people to modify and manage the same set of data from their respective locations fosters collaboration. Progress can occur more quickly without a single conduit through which all modifications must occur. And because the work is versioned, you need not fear that quality is the trade-off for losing that conduit—if some incorrect change is made to the data, just undo that change. (more)

This is a pretty good explanation of what it is, but it can be hard to imagine what that actually looks like or how you’d use it in practical terms.

So what can Subversion actually do for you?

It means you can have multiple developers working on a project without fear of one overwriting the other one’s work. Have you ever worked on a project with multiple developers, where everyone is working on the same codebase?

“Hey Bob – I’m working on index.php – don’t touch it for now. I’ll let you know when I’m done, okay?”

or how about

“CRAP! Did you make changes to view.php? You blew out my work! I spent half a day working on that frakking function!”

All of that goes away. Each developer can have their own version of the application or website (called branches), where the changes they make will not impact the other developers, and the changes can then be selectively merged into the main development area, or trunk.

It also means that you have a method by which to track all of the changes you’ve made to any given file. Each time you commit changes to the file, subversion assigns that change a unique revision number. This means that if you ever need to roll a file back to a specific revision, you can easily do so with a simple command.

A good example of where you might need to do this is where you’ve “fixed” a bug that broke something else on the site (and really, who hasn’t done that?). If you know the now-broken functionality was working before, you can roll back to a previous version of the changed file (or any version before that, if needed) to the point where the functionality wasn’t broken.

You can also compare revisions side by side, so if you don’t want to do a full rollback, you can see what changed from one revision to the next to figure out what you (or they) did to break it so you can undo just that part or find a new solution. Plus, since each developer has their own subversion username, you can see who did what (so you know who to fire/berate/pummel/defenestrate).

In short – whether you’re flying solo or working with a team, Subversion can help keep you sane, and bail your ass out when you need it most.

Sounds awesome, right? Let’s get started!

Before we go any further, there are some terms that you’ll need to understand in order to grok Subversion. Don’t worry too much if they are hard to remember – we’ll be using them a lot, and they’ll become second nature to you.

Repository - this is the central location where Subversion keeps all of the information about your files, folders, and revisions. The repository can live on the same server as your development environment if your hosting setup has Subversion installed, or it can live somewhere completely separate.

If your hosting company does not have Subversion installed, you can even use a third-party Subversion host like Beanstalk or Unfuddle, whose sole purpose is to store your repository, and only your repository. Your local files are still on your hard drive, and your development files are still on your webserver.

Working Copy - this is the set of files you work with to make changes to your code, build your application, etc. The working copy usually lives on your hard drive, and would replace the directory you upload from and download to if you were using FTP. Simply put, this is the copy of the files you are meant to be working with. You can have multiple working copies of a site for any single repository, and in fact, you would have multiple versions if you have multiple developers. Each developer would have their own working copy.

Import – Importing in Subversion allows you to pull your existing files into a new repository. So, for example, if you have a site that’s already halfway built before you have the epiphany to use version control, you’d import your existing stuff into the repository.

Check Out – If you already have files in a repository and need to create a new Working Copy, you’d use Check Out.

Update - Using the Update command pulls the most recent version from the repository. If you had multiple developers working on the same files, or if you’re working from multiple computers, you’d want to make sure you update before you start making any edits to the files. If you fail to update before you make changes, you risk running into a Conflict when you Commit. (see below)

Commit – When you’ve made changes to a file or files in your Working Copy and you’re ready to push those changes into the repository, you Commit them.

Conflict – A Conflict occurs when there are changes on both your local version (Working Copy) of a file and the Repository of that file. For example, Sally makes changes to the file sandwich.txt in the repository. Harry has just changed the file in his working copy and commits it. Sally doesn’t update her working copy before committing it and she gets a conflict (since Harry committed his version after Sally’s last Update, and Subversion therefore sees Sally’s version as out of date). More on predicting and resolving conflicts later.

Trunk - the location within your Working Copy where your main project files live.

Branches – individual copies of the project that allow each developer to have their own working version. Changes can be Committed without breaking the Trunk, and are then merged into the Trunk when they are deemed worthy. (More on this in the bonus section of part two.)

The image below gives a very high level view of how Subversion works.

The Repository is your gatekeeper. It is the part of Subversion that makes sure files don’t get over-written with outdated versions, and allows you to work in tandem with other developers without risking stepping on each others toes. Other than through the command line (to execute import, update, commit, and status commands) or through whatever gui application you prefer using, you never access the Repository directly.

How often to Commit?

This is largely a matter of preference. Some developers wait until entire classes or functions are added/edited/etc before committing a file. I personally tend to commit more often, since it gives me a more granular way of seeing what broke something else and rolling it back, etc – but the only wrong way to Commit is to not Commit at all. You do not need to commit every time you change every tiny thing, though. For example, if I had to do some copy changes, I wouldn’t Commit after changing each word. The revisions would be so broken down, it would be hard to find important changes in the sea of revisions.

You (and your team, if you’re working in a group) will find a Commit frequency that works for you, as you become more comfortable using Subversion, so don’t sweat it too much in the beginning.

Now that you know the lingo and what it does, you need to decide how you’re going to set up your subversion workflow. Check out the second part in this series!

Possibly related posts:

1. SVN Working Copies and Repository Locations In part one of this series, you learned what Subversion...
2. Introducing FBMHell.Com Good news, everyone! My compulsive need to make websites and...
3. Dropbox versus FolderShare for Syncing Files Between Computers In my eternal quest to sync up all of the...

We’re all human, and we all make mistakes and overlook important details sometimes – but the thing I can’t stand is making the same mistake twice. To prevent making the same mistakes twice, I have an ever-evolving list of questions that I use to create the tech brief for new projects.

In the hopes that this saves you some of the headaches I’ve had to suffer through, I’m making my list available to you. Some of these questions don’t have yes-or-no answers, and require additional discussion – but that’s okay. The point is that they were asked in the first place, and you’re including them in your plan.

Every time I start a new project, I run through this list of questions with the project managers or client, one by one, until I have all the answers I need – and after every project, I revisit this list of questions to see if there is anything I should have asked up-front that would have made the project go more smoothly.

Yes, this is long. But better to spend the time asking questions now and save yourself days or weeks worth of work later. Also, there may be whole sections you can skip entirely if they don’t pertain to your project – just be sure they really and truly don’t before you give them the brush-off.

I will be out of the country for a week in Belize starting oh-my-god-o’clock tomorrow morning, so this post is my gift to all of you who are stuck working on projects while I’m on a beach in Belize sipping Mai Tais. Enjoy!

Basics:

What is the main purpose of this website? General overview, specifically addressing goals the website or application hopes to accomplish. Online sales, brand reinforcement, etc. This answer doesn’t have to be long, but I find it helpful to include them here so that the tech process always compliments and enhances achieving those goals.

How “big” is this project? This is a generalized question and doesn’t require specifics most of the time – is it a 4 page site, a 40 page site, or a 400 page site. This helps to understand the basic scope. The answers to this question should include:

1. Approximate number of screens/pages in the website/application
2. What are the basic functions of the site? i.e.Registration, Game, Ecommerce, Search, catalog, photo upload, discussion boards, voting, etc

What data will be stored/accessed locally? Will the website/application require a database? You don’t need to make a concrete decision about what kind of database at this stage – just knowing there needs to be one is enough.

How will the site be updated?

1. Will it require a CMS?
2. What content is dynamic vs static?
3. How frequently is the data updated (hourly, daily, weekly, monthly, periodically)?
4. Where will the data come from? (client or administration back-end of any kind)
5. Who is responsible for updating the data?

What are the reporting needs?

1. Basic site traffic?
2. Will it require content‐specific reporting? (i.e. how many new users signed up between specific dates, etc.)

Will there be a mobile/WAP component? The answer to this question is usually “no” for the projects I work on, but it’s important to know in advance. Phone browsers these days are so similar to desktop web browsers that creating a WAP version of a site is far less trouble than it used to be, when you had to take black-and-white screens into consideration, etc.

What operating systems, browsers and browser versions are we targeting? Do we care about IE6 or other older browsers (pleasesaynopleasesaynopleasesayno)?

Are there additional considerations such as printer‐friendly versions, BOBBY/ADA‐compliance, age verification or other that we need to be aware of? Make sure you’re familiar with the COPPA-compliance guidelines before you create a site or application that asks for user information and doesn’t screen for the user’s age.

Domain Name & Hosting:

Where will this application/website be developed? If it will be developed on a different machine than its final hosting situation, we must provide time for file transfers, additional QA once the site is moved, etc.

Where will this application/website be hosted? If we are hosting, will it require a dedicated host, or virtual hosting environment?

If the client is hosting, have we confirmed that their server supports the technology we intend to use? This is a key point, but one that is often overlooked. If you’re expecting PHP on a Linux server and the client has an IIS box without PHP or MySQL, you need to know that up-front, so you can decide how to handle it. Maybe the client installs PHP and MySQL, or maybe you do the application in ASP – either way, the answer here has a huge impact on how you proceed, before even a line of code has been created, so you need to know that right away.

Also, if possible, try to obtain access to the hosting server as soon as possible, so you can run some basic configuration tests. One follower on Twitter remarked that the client confirmed that they had PHP and MySQL (on IIS), but the environment was not set up to allow PHP to talk to MySQL. Not something that’s impossible to fix, but if you’re pushing it close on your deadline, you want to know that right away so you can have the hosting company make whatever changes you need with plenty of time to spare. A simple phpinfo() would have spit out everything you needed to know (not to rub anything in, @derekobrien!). To be fair, I might have just assumed the same way he did, so it’s important to remind ourselves to check everything up front.

I would imagine that hosting blunder (and that was a blunder – who sets up PHP and MySQL but forgets to allow them to talk to each other?) is hopefully uncommon, but if you’re using libraries or modules like PEAR, cURL, imagemagik, the GD library, and so on, you’d best confirm that everything is all set up before you move forward.

In @derekobrien’s case, they weren’t granted server access until last minute, so he was caught off-guard by this. One way to protect yourself against issues like this is to set clear milestones in the tech brief or feature scope that you create based on these questions (which the client signs), with the caveat that if the client doesn’t provide server access by xyz date, the launch date can and will be pushed back, and additional budget may be required to get things up to snuff.

@derekobrien also included a clause in the fine print that says “If your server admin is a fool we reserve right to point and laugh at you.” I generally consider that implied, but it’s just as good in writing

Will it require its own domain name?

1. If yes, will the client provide, or will we?
2. If yes, we must allow time for propagation
3. If no, at what url will this live? (sub‐domain of noise, sub‐domain of primary client domain, etc)
4. If sub‐domain of client, we must provide time to work with the client’s IT dept to configure DNS settings

Will we need to manage any email accounts for the project? If so, what are the account names, and are they pop3, IMAP or forwarding accounts? Who will be checking them?

Will this project be migrated to the final hosting location from an existing location? If so, a migration plan (including e‐mail address, DNS, content, database, etc migration should be created.)

Is this project ongoing, or for a limited time? If for a limited time:

1. What ongoing service or support will be required? Webmaster support email? Unsubscribe administration?
2. What is the plan for the domain name and/or website once the project is over? Do we keep hosting the project? Do we let the domain name expire, or simply redirect it to the main client site?

If the project is hosted on a server we are managing, server setup should include:

1. Realistic bandwidth estimate. We should confirm with the hosting company we select that if we surpass anticipated bandwidth, there will be no interruption in services. (Extra charges will apply, but service should NOT be suspended for bandwidth issues.)
2. Maximum throughput configuration available. There is generally an insignificant additional monthly charge for this.
3. If the project relies heavily on mySQL, we should consider making adjustments to the my.conf file to tune the database configuration for optimal settings. (I.e. if the database queries are largely SELECTs, optimize for SELECTS, etc.)
4. Fine‐tune the apache httpd.conf file to allow for maximum concurrent connections

Backup and Restore – if we are hosting the project on a server we manage, dedicated or virtual, some level of backup must be implemented for every account.Backup should include files, user data, and applicable databases – and a restoration plan should be created, should catastrophic system failure occur. The backup process MUST be tested during non-emergency circumstances. An untested backup is no better than no backup at all.

Flash/Video:

Will there be substantial flash or video aspects to this project? If yes, we should consider hosting arrangements and ensure we have the bandwidth available and ensure the throughput is set up to handle maximum traffic.

If the primary site or application content is Flash‐based, we must budget time to create an SEO‐optimized version of the page in plain text. Copy will need to be obtained from the client, and MUST accurately reflect the true content of the Flash. Attempts to keyword bomb or deceive search engines will result in being blocked from the search engine altogether.

Email:

Will the application or website be communicating with users via email or text messages? If so, we may wish to consider outsourcing email/text messaging for ease of management and to circumvent potential SPAM blacklisting issues. This decision needs to be made on a case‐by‐case basis.

Integration:

Will the application or website be required to interface (push or pull) with a third party system or service? If yes, documentation on the integration should be obtained at the beginning of the development planning so any potential obstacles can be addressed.

User and Content Filtering:

In projects where users will be contributing or creating content using the tools we develop, is there a need to build in support for:

1. Banning or blocking specific users by username or IP address?
2. Moderating content before it is displayed publicly or at least the ability for and administrator to delete to unapproved content to remove it.

If yes, by what method will offensive material be flagged as offensive? Does the application require a “report this content” function, and if so, what needs to happen when content is flagged? Who is notified, and what actions do they take? Should the system automatically unapprove content that is flagged many times?

Scrubbing or filtering bad words. If yes, what action should be taken if an offensive word is found? (i.e. is the offensive word replaced with ****, is it rejected by the system, etc.)

Pre‐Existing & New Content:

Does this project require us to import existing client data or content into the application? If so, in what format will the client be providing this data? (Excel, csv, Word, etc.) Adequate time must be allowed to scrub the data and create custom import scripts, and then to QA the imported data.

If content being provided runs on a timeline (such a daily quiz, where a new question is presented every day), do we need to set up an alert system that notifies an administrator if content is about to or has already run out?

Will there be ongoing new content that would be appropriate for use in an RSS feed? (Events, articles, blog content, etc.)

User Support:

What options does the user have if they have experiencing a problem with the application or website? Is there a Help/Tech FAQ page, a contact page, or some other way that they can reach out to us for assistance? What email address should be used for replies?

If we are going to be sending the user emails or text messages, we should outline the nature and frequency of this communication very clearly on a page available to the user.

A privacy policy should be built into the site or application whenever we are collecting any information from the user.

How does the user opt out? We should make it very easy for a user to globally opt out of our communications. Where applicable, on the opt‐out form, we should ask the user why they chose to opt out so we can better tailor future communications. Any email or text communication should require a double‐opt‐in confirmation.

Statistics & Reporting:

What aggregate statistical reporting needs to be done on this website/application? (Omniture, Google Analytics, Refresh Analytics for FB apps)

Do we plan on implementing click heatmap technology and/or multiple page versions for conversion rate evaluations?

Marketing and Promotion:

1. What media is driving traffic to this site? Online/Offline?
2. What is the schedule for that media?
3. What is the total exposure?
4. Are there any specific activities that would drive spikes in traffic? Superbowl Ad, etc.

PDF

So, that’s my list. After all of the questions are answered (which usually doesn’t happen all at once – it very often requires a bit of back and forth with the client and project managers), I create a tech brief or feature scope document based on the answers I from this questionnaire.

If the client doesn’t know the answers to some of the questions (“are you running linux or Microsoft?”), I do my best to find out who does. If the client can’t decide on something “do you need a content management system?”), I advise my project managers that we have to be given authority to make that decision for them. NO development will be done until the tech brief is done. Period.

I then get the client to SIGN the scope/brief so that they agree, in writing, to everything we’ve decided – and more importantly, what I expect from them, when I expect it, and what they can expect if I don’t get it on time – that way when they don’t deliver server access or copy/creative assets on time, there are no surprises when I tell them that we are not going to make their deadline.

The tech brief is written to protect both parties, the client and the service provider. When done properly, it helps manage client expectations, and protects you from being expected to deliver something that was not in the scope. Everyone knows what happens next, how much it will cost, and what the final product is supposed to do.

I’ll be updating this as new screw-ups happen and we (hopefully) continue to learn from them.

Leave your own in the comments, and feel free to download the (slightly longer) PDF version if it will help you do battle with middle management that doesn’t understand why you have to take so much time to plan your projects.

Possibly related posts:

1. GUI Planning Made Easy with the Pencil Project Designing a good GUI is arguably one of the most...
2. Funky characters in HTML mail using PHPMailer While working on a client project, I ended up having...
3. Cheap or Free Website Status Monitoring Its a call you never, ever want to get. “My...