Development, Communication, Documentation

A Developer Out of Control

Jack is a web developer for a ten-person consulting firm. Although he has no formal training in computer science, he has 5 years of development experience with a range of open source tools and is passionate about his work. Jack is tasked with building a new web application to accept advertisements for an online publication. Because the client's contact is familiar with web development technologies, Jack tells his project manager he is willing to serve as the client liaison and work directly with the client on a daily basis. As usual, he will check in with his project manager each week to provide a status update.

The project starts out very well. Jack is on budget, and the client is happy. The consulting firm's project manager begins to give Jack more leeway because everything is moving along so smoothly, and decides to have meetings every other week.

Jack really likes the application he is developing and decides to try a new development framework. Because this is really a technical decision, he does not feel that he needs to get clearance. Jack is off and running. About a month into the project, he notices a couple of features that could really improve the user experience and suggests them to the client. The client is excited about the improvements and makes a few recommendations of his own. Jack means to make a note of these changes and tell his project manager about them, but on the day of their regular progress meeting—which now takes place every 2 weeks—the project manager was away at a training session. However, the changes are not that big, so he decides he can remember them all.

Jack keeps plugging away. Some minor technical glitches crop up between the framework he decided to use and a few of the improvements he and the client agreed to implement. However, he finds a workaround with only a couple of days' worth of extra effort.

One afternoon, the client calls Jack and excitedly tells him that the prototype system is so popular that two new clients have signed onto the project, so they will need to extend the application to enable clients from multiple magazines to use the system. Initially, Jack is nervous about this new technical direction because some of the previous modifications, combined with this new requirement and his selection of a new framework, are causing some technical problems.

Jack lets deadlines on other projects slip by as he tackles one problem after another. He always feels like he is just a day or two from being done until a new problem or bug creeps in.

Jack's project manager hastily calls a meeting to discuss the missed deadlines on several other projects; it has now been nearly 4 weeks since their last meeting. Jack proudly demonstrates all of the new features and increased functionality he has built into the system—including a few graphical flourishes of his own—and explains that he is very close to solving his latest technical issue. Finally, he discloses that the new coding framework he selected is causing a few problems.

He notices that his project manager is becoming increasingly agitated. The project manager explains that Jack is already 20% over budget on the project and cannot understand why he has adopted a new development framework on his own—one that no one else at the consulting firm uses—which means that Jack is effectively the only person who can continue working on this project. To Jack's surprise, the project manager tells him to stop work on the project while he calls a meeting with the company's management to determine how to proceed.

In this case Jack and the project manager are both at fault. Jack overstepped his role as a developer, and the project manager allowed this to happen. It is exceptionally hard for a developer who is deeply involved in the details of programming a system to clearly understand the broad context into which his work will fit. This is an important role for the project manager. When the project manager and developer don't clearly and consistently communicate, problems can emerge rapidly.

This chapter offers guidance on keeping the project team on track and ensuring that documentation is being prepared as the team progresses.

Keeping the Client Updated

It is likely that the bulk of the project schedule will be taken up by the development phase, which involves little communication between you and the client. This is normal if it happens, but it is essential to provide regular updates to the client during this period.

A simple e-mail, sent once a week, is sufficient to keep the client updated on the status of the project. Keep the e-mail brief and mention a few specific milestones that have been completed, the major upcoming milestones, and reconfirm the launch date of the project (if it is still on track).

It is also likely that during the development phase you will hit upon an issue that requires some client input to resolve. This is an opportune time to bring the client into the decision process. To protect against the unexpected or the unwise suggestion, be sure to frame possible solutions as specific options in an e-mail, and request a decision on the option the client feels is best. You might consider scheduling a brief conference call to discuss the issue at hand, beginning the call with a quick project status update.

Bringing the client into a guided decision has several benefits:

• The client feels like part of the project process.
• The client gets to buy into the decision. This helps to manage expectations about the issue at a later date, as they were part of the decision-making process.
• The project is protected by defining the possible solutions from the start. This helps ensure that no options do more harm than good overall.

Replying Quickly

An easy way to keep a client satisfied and confident in the project process is to reply to e-mails in a timely manner. If the client sends a note about a problem, reply quickly that your team is investigating the issue and identify when you will update them next. A quick reply will be appreciated and alleviates any pressure on the sender (say, if she is receiving pressure about the issue from her own internal team).

Because people usually are slow to respond to e-mails, your client will appreciate a prompt reply. It is an easy, low-cost way to make a positive impact on your client.

For more details, see “Be Responsive” in Chapter 11.

Tips for Writing E-mails

Love it or hate it, e-mail has become the dominant mode of communication among teams in business. Like any tool, an e-mail can be used well or poorly. Let's look at how to use e-mail effectively.

Professionalism

Because e-mails have such low cost (easy to write, free to deliver, instant arrival), the written quality of e-mail tends to degrade to simple, curt messages. Resist this temptation. An e-mail to a client should be complete, spelled correctly, short, and relevant.

Here are our e-mail tips:

• Start the e-mail with a friendly “Hi {Name}” or “Hi Team” when addressed to several people.
• Be polite; for example, use “kindly” and “thanks for your note.”
• Limit the e-mail to three or four paragraphs.
• Limit paragraphs to three or four sentences.
• Take time to write a simple, respectful and professional e-mail—even in response to one-line e-mails. In doing so, you maintain a professional demeanor and make clients appreciative.

What's in a CC?

A CC on an e-mail is one of two things:

• A way to keep a team member informed; or,
• A handy way to lend weight to an e-mail by keeping the boss informed.

While a BCC is a soft notification (in that you let the boss know something without the recipient's knowledge), a CC is a hard notification in that it adds authoritative weight to any e-mail sent. A BCC is used to let a valued employee save face while still keeping the boss in the loop. A CC is used to reinforce the e-mail with the superior authority of the person CC'ed.

When used correctly, a CC can say, “Hey! This is important, as I am letting the boss know I told you this.”

Don't Be Rude

Do not be rude in e-mails. Do not place blame, and do not write something to make your wounded self feel better. Try to be unflappable.

If you are writing to check in on a client who has not responded or who has dropped the ball on something, say something like, “I just wanted to check in on the {whatever project}. If there is anything I can do to help, kindly let me know.”

Your Vacation Auto-Response Message Is Probably Wrong

Most people do not set up e-mail vacation auto-replies correctly and typically commit a few usability gaffes in these auto-responders.

Here are few helpful guidelines when configuring your auto-response:

1. Be absolutely clear to the reader exactly what date you are back at your desk reading e-mail.
2. Recipients should only receive a repeat response once every 5 days.
3. Include coverage contact information: who can the reader contact while you are away if they need help?
4. Always include the original subject line in the auto-response e-mail.
5. Avoid stating when you started your vacation; focus on when you will return and be available.

Guidelines 1 through 3 are a simple matter of professional manners and responsibility.

Guideline 4 is important for two reasons: including the original subject line reminds the recipient of the source e-mail that generated the message (and thus roughly what date they discovered you were on vacation). In addition, including the subject line decreases spam when vacation responses are sent to e-mail addresses that feed into issue-tracking systems.

Guideline 5 keeps the client focused on when they might expect a reply, rather than thinking about your wonderful vacation.

The Power of Checklists

A checklist is a simple little thing: a list of items written in a meaningful order. Beyond your own lists for the grocery store and for preparing for travel, you are surrounded by a variety of invisible checklists that keep you safe, secure, and happy.

For example, say you are taking a two-hour flight from Boston to Washington, DC. This trip seems routine from the passenger's perspective, with a short flight, nice flight attendants (maybe), and an easy landing. But this is made possible by trained professionals piloting a marvel of engineering that took decades to design, billions of dollars to build, and requires thousands of small mechanical components to work in concert. The complexity of a commercial airliner is made abundantly clear to us lay people if we catch of glimpse of the cockpit control deck, complete with hundreds of dials, knobs, switches, readouts, and gauges. And yet at the end of a flight, you are still alive and the pilots do not seem all that stressed while standing in the cockpit door and saying goodbye to deplaning passengers.

How is all of this possible? A myriad of factors, really: government regulations, the wide use of safety technologies, modern computers, and increasingly sophisticated airplanes. And, of course, one more important piece of safety is the preflight checklist. If you ever saw the pilot looking at a clipboard before the plane departed, she was probably running through the preflight checklist.

This checklist includes steps to verify everything from having enough fuel to the right oil levels to testing critical components. These checks might seem obvious, but there are dozens of them, and one or two can be easily overlooked. Most often, the checklist does not find any problems, but pilots repeat the checks before every flight, every day, for their entire aviation career. Over and over again, they run this same checklist.

Why? First, it is important to recall the 80/20 rule. (See “The 80/20 Rule” in Chapter 4 for a more complete explanation.) Put simply, the 80/20 rule states that often, in an engineering system, the ratio of 80/20 appears.

The 80/20 rule is as much about a sort of engineering golden ratio as it about learning to examine solutions to a problem by assessing how much impact an individual solution offers to addressing your problem.

There are thousands of ways that an airplane can crash. Some are possible to check before a flight, and some are not. However, by checking explicitly for problems that cause a greater proportion of crashes, you can substantially reduce risk while only looking at a small subset of the overall number of accident causes. Resources are never unlimited, whether that is time, money, or expertise. When you only have time to check 20 components, you want to be checking the right 20 components that prevent the most possible points of failure.

And this is what the preflight checklist is designed to do. Because of the wide use of checklists in aviation, airplane disasters in the West tend to be caused by outlier situations that are hard or impossible to screen out before they happen—rare weather phenomena, acute mechanical component failure, acts of terrorism—and not by the more detectable, common failures that plagued aviation in the early years of powered flight.

A checklist thrives in situations where the 80/20 rule thrives. The goal of the checklist is simple: improve the stability of a system by checking the most common detectable causes of failure frequently.

Checklists are widely used in commercial aviation and the military, and are becoming more widely used in hospitals, where they are showing early but dramatic results in improving care.¹ The checklist has utility for project management in software and web design as well.

Here are a few ways you can use checklists in your own projects:

A sanity health checklist: this is a set of checks that assesses the health of a web application, looking at common causes of failure on the entire stack, from the server or operating system level to the application level. Items might include the following:

• Does the server have enough free disk space?
• Are there any security patches for the operating system pending installation?
• Does a port scan reveal any unexpected open ports (indicating a firewall failure)?
• In the past 24 hours, have there been any log messages of concern?
• Did the last backup succeed?
• Is e-mail successfully sending from the server?

This checklist touches upon the common areas where an application can fail, such as dependent component failure (e-mail, backups, firewall) or operating system problems (lack of disk space from runaway log files, missing patches, error log entries).

A patch checklist: these are the steps that outline the process of applying a patch to a live production site. Steps might include

• E-mailing the client to alert them the patch has started
• Putting the application into offline mode for the patch
• Making a manual backup of the database and code before the patch
• A few specific tests to run on different parts of the application to validate the patch is not causing major issues (could be the separate upgrade checklist mentioned next)
• E-mailing the client to alert them the patch is complete

An upgrade checklist: this is a series of checks on the most fragile parts of the application that you run after you patch new features or issue fixes into the production system. It is a form of a testing checklist that your developer should conduct as the last step in the patch process.

__________

A testing checklist: this is a guide for those doing quality assurance testing on your application. See “Creating a Testing Checklist” in Chapter 9 for more information.

A launch checklist: this is a list of important launch-time configuration adjustments to apply to ensure a smooth, professional launch of a project. See “The Launch Checklist” in Chapter 9 for details.

Here are some general tips for creating checklists:

• When creating a new checklist, start from the last one you prepared for another project. You will not keep every item you had, but it will be a good starting point.
• Ask different team members what they think are the most likely three or four points of failure.
• When a problem occurs that your checklist did not catch, take a moment to consider if there is a check that can be added while keeping the checklist efficient.
• Think back to the major problems you have had with other applications in the past. There are likely good checks in these painful memories.
• Parts of your system that rely on third-party components are likely to be fragile (by design; if you do not control it, you cannot trust it). Check those.

Investing a small amount of time to create and use an efficient, targeted checklist will help prevent major system problems that might otherwise consume a far greater amount of your already scarce resources.

Don't Avoid the Pain; Go Toward It

Let's talk about the no-win-scenario (NWS) bug. You know this bug. You have no time left in the budget to troubleshoot this issue. The programmers insist there is no quick option, it will just take time. Meaning hours. Hours that are no longer available in the project budget. So the bug report sits in your queue as you are hamstrung by indecision. With no good choice to make, who wants to commit to the least bad option?

We struggle with the NWS bugs, often obsessing that there must be a clever, time-beating solution to the issue. But there is not. If you have great programmers around you and your initial questions and discussion did not produce any insight, then there likely isn't any to be found.

Just accept that the least bad option is the best option, make a decision, and move on. Do not ignore the issue. If you do, it will start to affect new modules developed in your application. Your programmers will (naturally) forget the intricacies of the issue, and so will you. You will need more time later to relearn the issue.

Open decisions in your queue are a drag on your own morale, as you can feel their burden and feel your brain nagging at you to make a decision.

Do not avoid the pain. If you have pain right there in front of you, it should be an indicator to move toward a decision. You should want to be rid of the pain by dealing with it, embracing it, and moving forward. Do not ignore it. A little pain now saves you a lot of pain later.

Keeping Documentation

Documentation is hard—mostly because very few people enjoy writing down what they are doing.

There are several kinds of documentation that you will need to ensure the success of your project. Most projects that are $100K or higher will need each of these types of documentation.

The key here is to ensure that reliable systems are in place to track the system documentation. As we review each type of documentation that you need for a successful project, we will offer our hands-on observations about some of our favorite systems for tracking these changes.

Documenting Code

When a developer writes custom code, he needs to add comments throughout explaining what he is doing. This makes it significantly easier for someone (including the same developer) to revisit the code later and make changes. It's tempting to think that you will never need to revise your custom code, but 90% of the time, you would be wrong. Here is an example of some simple commenting that you would expect to see in a developer's code:

This kind of documentation should always appear in your development files, inline with the code. Many developers provide very few comments on their code, or none at all, unless they know that someone is reviewing the code. The best way to ensure that your code is well-commented is to have regular code reviews where a technical project manager or another developer reads through the code and make recommendations.

Recommendation: perform monthly code reviews to ensure that developer code is well-commented.

Documenting the System Architecture

The system architecture is typically developed early in the project. If you have followed our advice, you will most likely have a technical specification that outlines the system architecture. However, if you do not have this, you need to capture the relevant details so that developers understand the full scope of the system and so that when you come back to the project later, you can remember the specifics.

Sometimes the simplest way to do this is to create a graphic with a visual representation of how the different parts of the system work together. This does not have to be highly technical, but it should convey at a glance how the system operates. See Figure 8-1 for an example.

Recommendation: document the system architecture in the technical specification, or in a separate graphical document.

Figure 8-1. A system architecture for a cluster to power a widely-used web application.

Documenting System Administration Settings

Team members can waste a lot of time trying to find usernames, passwords, and other system administration settings. If there is no centralized location to store this information, individual team members will begin keeping “cheat sheets” with the information on a piece of paper in their desk or in a file on their computer. Not only is this not secure, but it also complicates changing settings or passwords.

Wikis are an excellent way to store system administration information. A wiki is a series of shared web pages. Each change is tracked, so it is easy to see what information has changed. Individual team members can be granted access to view or edit pages, based on their needs. When you have configuration changes—for example, if you create a new development site—you simply add the details to the wiki. All team members who need access can then access the wiki to obtain this information.

Figure 8-2 shows a screenshot of the template we use for client pages on the Urban Insight wiki.

Figure 8-2. A screenshot of a sample wiki page based on a fictional client, with all confidential information removed.

Recommendation: track system administration details using a wiki.

Documenting Changes over Time

Most successful web applications change over time as the application is refined and upgraded and as new features are added. Documenting the changes that occur over the life a system is one of the most challenging aspects of documentation.

For example, say you finish a modest project and have the developer deploy the changes to the production server. The correct code is launched, and the project is successful. Six months later, you ask another developer to make some modest refinements requested by the client. However, unbeknownst to the current developer, the initial developer made some changes on production that he failed to make on the local development copy. The programmer making refinements is working on the development copy of the application, not production, and when she pushes her refinements they will inadvertently overwrite the working code that's already there.

Version control is an elegant solution this problem. Changes to code are usually identified by a number or letter code, termed the “revision.” For example, an initial set of files is “revision 1.” When the first change is made, the resulting set is “revision 2,” and so on. Each revision is associated with a timestamp and the person making the change. Revisions can be compared, restored, and with some types of files, merged. Version control makes it possible to see previous changes made to a file, and also to view the comments that the developer provided when committing the change.

Use Version Control

A version control system provides a system for your development team to track the changes to the source code of your project over time. A great version control system can provide a reference for every past version of a file (so nothing is lost), and keep a record of every code change. This can be helpful to understand what the thinking was when an engineer made a change.

Figure 8-3 shows the note left by a developer when he completed work on a routine to show receipts.

Figure 8-3. A log entry from a single code submission from a developer in Beanstalk

Case Tracking

Tracking individual requests for changes on a system is an important aspect of documentation. Often, tracking these changes goes hand-in-hand with the code changes that you will track in a version control system. Let's use the word case to refer to a specific and definable set of requested changes to a system. For example, say that your client asks you to modify your system to include a new screen that tracks changes in addresses over time.

If you were using a case tracking system, you would use the system to create a case, which would be assigned a number—say Case #1. Any communication about this particular request would be stored in the case tracking system so that you have a repository where all communications about this request are stored. For example, if you and your client discussed the specifications in an e-mail, you might send a copy of the e-mail to your case tracking system, so that e-mail becomes part of the permanent record of discussion. When you finally decide what to develop, your wireframes would be uploaded and attached to the case. When you are ready to begin development, you might create subcases—for example, Case #2 for development of the interface and Case #3 for testing. Both of these cases would be related to Case #1, so you could later identify the work that was performed.

Case tracking systems also can record the amount of time involved on a project and help you to plan your schedule based on available development capacity. Figure 8-4 shows the task view screen of an issue tracker that details a feature for a public web site.

Recommendation: use a case tracking system to document requests and changes over time. (See the Appendix for suggestions.)

Figure 8-4. The ticket view screen in FogBugz, a popular issue tracking system

The Weekly Developer Meeting

The relationship between a project manager and a developer is much like that of a parent and a teenager: there is very little you can do as a parent to change what a teenager thinks or does. Your job is to try and nudge them in a slightly different direction when they are careening headlong off a cliff edge. (This in no way means to disparage programmers. It is programmers—not project managers—who make a great project great. However, in our experience, programmers tend not to take the big picture into consideration, but focus instead on the immediate problem at hand.)

Micromanagement is an ineffective project management technique for a variety of reasons:

• People will be frustrated that you do not trust their abilities.
• You do not like working under a micromanager, so why would anyone else?
• It takes too much time. Your time is at a premium, so spend it where it will have the most positive impact on the project.
• If a team member really needs constant supervision to be effective, you have a personnel issue, not a management issue.

The key is to maintain oversight and control of your team, but give them enough breathing room. We recommend a one-on-one weekly meeting.

The weekly meeting can be short, maybe 30 minutes. In this meeting, you have three main goals:

• Review the status of every outstanding project.
• Set a Clear priority order for what needs to get done this week.
• Discuss any complex tasks that would benefit from planning discussion.

When you review the status of every ongoing project, you can see if the developer has run into any issues that are making the task more complex or are requiring more time than expected. Focus on these hiccups in your meeting and be determined to find solutions.

Set a clear priority order, making it clear to the developer what you need accomplished over the coming week. This is also your main tool to manage the schedules of your various promises to clients about when tasks will be complete. Limit this to just two or three tasks. Anything more just will not be possible in a week (because something always unexpected happens with a client).

Lastly, use the weekly meeting to review any complex tasks that the developer will work on that week. This is a good time to do a “gut check” and see how the developer might approach the task. Most of the time their programmer instincts will serve them well, but it is important to make sure you know the general approach they are taking. Sometimes, you can identify and remove any mitigating factors they might not be aware of, and steer their work in a different direction.

Monday is a great day to have the weekly meeting. Team members will be fresh from a restful weekend and you can frame the week as a distinct unit. Once you lose the developer for a weekend of fun, they will not remember what they were talking about the week before.

Finally, there are two additional benefits to a weekly one-on-one meeting. First, this is a setting that encourages frank feedback because others are not watching. And second, taking the time to meet individually helps make team members feel valued.²

Wrapping Up

In this chapter we looked at how to manage the development process, keep the client updated, and use checklists to ensure consistent quality. As development winds down, you will need to begin to validate your project with testing.

No one really likes testing, but it's vital to ensuring that you produce a high-quality product. Bugs in software are not a reflection of mistakes or poor programming skills. They are a reflection of the reality that technology is a hard, complicated game that involves subtle interactions with many independent systems (such as other code modules you have written, third-party applications you integrate with, and hardware you run on). Software bugs indicate a failure of project management, not of development.

Naturally, the next chapter focuses on testing. We cover the different kinds of testing that a project can involve, how to write a testing checklist (which gets your client to do some of testing work for you), and how to manage a client beta test. We wrap up with guidance on how to conduct useful but easy usability tests and share a war story about a beta test gone horribly wrong.

__________