By this time in the project, you should have a good set of requirements and a clear sense of the project features. You should also be able to confidently maintain project momentum and address common situations that cause delay. Now that you know what to build and how to keep the project moving, it's a good idea to first document the technical aspects of what your team is building.
Some technical documentation is meant to be shared with the client, and some is meant only for consumption by your project team. There are also many flavors of technical documentation—wireframes, design mock-ups, HTML mock-ups, and technical specifications, to name a few—so it's important to understand which documents are helpful when. What each format has in common is that they unify the concepts of what the project will be in a more visual and holistic manner than a dry bullet list of requirements could ever convey.
Technical documentation should not become a time sink. Ideally, it is another efficient step to help manage the expectations of the client and your team. In this chapter, we detail the most common types of technical documentation and guide you through how to create them.
In addition, we cover tips for how best to share work with your client, how to manage a design process that doesn't break the budget, and even how to create and document a database for a project.
The first step in preparing technical documentation is identifying exactly what kind of documentation you need for your project. Let's start by looking at how you can pick the right format.
A technical specification will assume different forms depending on the kind of project you are working on:
There are many different kinds of mock-ups you can prepare; these include the following:
In both a public website project and a custom software project, it is best to prepare a set of wireframes and seek client approval before you prepare some kind of mock-up. A visual mock-up (design or HTML mock-up) will take more time to create and more time to refine from client feedback than a wireframe, so it is helpful to nail down the core layout before the design phase.
A wireframe will also set the structure that the design mock-ups will need to follow, meaning the designer can focus on presenting the same structure visually in different ways. The client will be able to focus easily on the visual differences in the mock-ups, rather than the structural elements (which should already be set by the wireframes).
What is the difference between a visual mock-up and a wireframe? Take this example: a visual mock-up for a web site redesign project would include the logo being used for the project in the header of the mock-up. On a wireframe, the logo would likely be a square box labeled, “logo.” See “Preparing Screen Mock-Ups” later in this chapter for some examples of wireframes and their resulting mock-ups.
For a public web site project that does not involve much custom development, you can prepare a set of wireframes for client review. Once refined and approved, you can hand these wireframes and the requirements over to the designer, who can prepare the design mock-ups.
For a custom software project, there usually is not as much of a design component (beyond meeting the client's basic branding requirements) so much as an interactive design process. It is vital at this phase to show how the application will work, how the interaction between the user and the application will function, and how the screens will connect the workflow logically in the application. A set of HTML mock-ups will work best in this situation.
In a custom software project, the difference between individual pages will be much greater than the differences between individual pages in a public web site project, where the basic layout of content pages tends to be more consistent. Because of this, in a custom project you will need to create many more HTML mock-ups than traditional wireframes or design mock-ups.
For smaller custom software projects, a set of HTML mock-up screens (and the database schema, discussed later) are probably all you need for technical documentation. The developer will happily take the screens you prepared and start building the business logic to support the implied functionality. A good set of HTML mock-up screens for a smaller custom project can be so instructive that your developers might never open the requirements document during development.
The amount of detail you will need will vary. For wireframes and design mock-ups, prepare a home page and a sample content page. For HTML mock-ups, prepare a mock-up of every page, every form, every filter, and every control in the application.
Figure 7-1 details the HTML mock-up of a student database listing and search screen. Looking at the mock-up, you would not know that none of the functionality is present.
A clear set of mock-up screens has many benefits:
For a more complex custom software project, you will need to prepare a technical specification. A technical specification is actually quite simple. It is a written description of your HTML mock-ups and of all of your project's features, and is intended to serve as a development guide to your project team.
A technical specification describes everything that goes on behind the scenes or that is not immediately apparent in your HTML mock-ups. A spec is most helpful for complex or larger custom software projects. A good way to find out if you need a technical specification is to look at your requirements.
Ask yourself these questions:
If you answered yes to any of these questions, then you probably need a technical specification. Let's look at an example.
Say you have a project to build a series of web forms for editing structured data such as contact records. The HTML mock-up screens you prepare will make it clear where fields go, how the forms are laid out, and how the workflow will work. Additionally, there is really only one way (in a specific technical platform) to create a web form that allows users to edit data. There is not much in the way of discussion or possibilities of “gotchas” in building this kind of project.
However, if you also have a series of requirements to build an e-mail newsletter system into the contact database then you need a technical specification. Why? Because there will be many technical decisions that your programmers will have to make in order to build an e-mail newsletter system that would not be addressed in the requirements document.
______________
1 Joel Spolsky, “Painless Functional Specifications,“ www.joelonsoftware.com/articles/fog0000000036.html
, October 2, 2000.
Here are just a few questions: How will e-mails be sent? Will they be queued and sent by an automated process, or sent immediately? Will the process run hourly, daily, every 10 minutes? How will we handle the processes running over each other? How will the process be set up on the server? Do we need a separate machine for handling the queue? How will we handle bounces? Prunes? Unsubscribe requests? Do we need to make any DNS changes so our e-mails do not get flagged as spam?
Too many unanswered questions are deadly to a project. Leaving the wrong kind of decisions to your programmers (and not answering them up front) will likely cause problems of budget, scope creep, schedule, scalability, and fault tolerance (often a challenge in e-mail systems) in your project.
Figure 7-2 is a real technical specification for a large, internal, custom ASP.NET project for a major university.
To bring it all together, here is what to use when and where and how:
For a typical public design web project, the process would be
For a typical midsize custom software project, the process would be
For a typical larger custom software project, the process would be
This guide is not about the design process, so we will not delve into tips on the art of design (which is a good thing, because we do not have any). However, here are some general pointers that will help make the mock-up phase a breeze.
For custom software projects:
For public web site design projects, it is most helpful to have a great checklist of questions to ask in the requirements gathering phase about design, such as
When the wireframes are ready, send them to the client to review and set up a meeting to discuss them. Begin the meeting by explaining what each element in the wireframe represents. This helps ensure that everything is clear to the client.
Let's look at several examples. The wireframe in Figure 7-3 was for a dashboard for nonpublic users on a news-driven site. This is really a web application design exercise and not a public web site design exercise, and this page was part of a larger suite of tools to facilitate running a news site. This wireframe was created using Balsamiq Mockups, a wireframing software tool. Figure 7-4 shows the real web page that resulted from this initial wireframe.
The wireframe in Figure 7-5 was for a web development project whose goal was to encourage public participation in the McHenry County, Illinois, 2040 Long Range Transportation Plan. This wireframe was created by Urban Insight project manager Chris Loos using Mockups. Figure 7-6 shows the homepage.
The wireframe in Figure 7-7 was created to specify a web-based video gallery for the Los Angeles County Museum of Art. This wireframe was created by Urban Insight project manager Kurt Rademakers, PMP, using Microsoft Visio, which is often favored by project managers who have to create many wireframes that share common elements. The web page is shown in Figure 7-8.
In this case, because a clearly defined design for the web site already existed, the project team went directly from wireframes to implementation.
It is important to present the wireframes and mock-ups to the client in a professional manner:
When preparing wireframes to share with the client, consider the following:
NOTE See the Appendix for neat wireframe and mock-up tools that we have found helpful.
The visual design aspect of a web site development project tends to be the most fun for both you and your client, but it also has the potential to throw the project off track. Let's face it: design is subjective. We have seen perfectly professional and usable designs destroyed by a committee of non-design professionals who all wanted to add their own signature touches during the design review process.
Here are several subtle tactics for keeping the visual design aspect of your project on track.
Because it is subjective, the design process can go on for a long time unless you constrain it. The best way to do this is to be explicit about what the design process will include and associate a cost with continued design revisions. Here is a model that we have found can work well:
After you have created the initial set of three designs, it is often useful to schedule at least one and probably two design review meetings with your client to carefully walk through each of the designs. Most designers create the initial designs as images using Photoshop or Illustrator, with the mock-ups presented as images on a web page, emulating the look of the finished web site. This presentation can confuse clients, leading them to believe that the application or web site is already completed.
During your design meeting, it is useful to cover the following points:
Here are a few additional things we have learned over the years:
Be patient, positive, clear, and concise, and with a little luck, your design process will move ahead flawlessly.
Creating the database for your custom project should be a very satisfying phase for three important reasons:
Some technical project managers may be up to the task of creating a database schema for the project on their own. However, database design is not likely to be part of the skill set of most project managers.
If you have limited or no experience with database design, you may want to work alongside a developer to create the database schema or delegate this task to an experienced developer, and have her walk you through the schema she creates.
We do find that project managers should be involved in the database design phase, as it provides three unique benefits:
In most cases, it is easiest to build the database schema after you complete and refine the HTML mock-ups. The mock-ups will go through several revisions, following internal and external feedback, so starting the schema too early may waste time with needed revisions. Once the mock-ups are completed, you can design the database alone or in tandem with writing the technical specification (if you are writing one).
For a project that will not have a technical specification, you can simply go through the HTML mock-ups one at a time and create the necessary database structure for each page in the application. If you are writing a technical specification for the project, write the database schema at the same time. This will help you conceptualize the technical architecture of the application.
As when designing the schema for a project with just mock-ups, try building the parts of the database needed to support each section as you write the technical specification.
Here are some general tips that can help with the database phase, whether you are doing it yourself or working with a developer:
Why bother creating the database schema before you start development? As with writing a technical specification, creating the actual database needed to support all features in the site will likely reveal technical issues you need to discuss with your team and solve now, before development starts. Fixing a problem during development takes more programming hours and costs more money than if it had been fixed earlier. The most expensive line item in your project budget is likely human hours; guard them jealously.
A technical specification describes everything that goes on behind the scenes or is not immediately apparent in your HTML mock-ups. The spec should include screenshots of the prototype screens you prepared. This is important when you have a more complex interface with lots of business logic.
This is also a good place to set the tone for the technical architecture and basis from which your developers will write code. Before any coding starts, you can protect the project development from going down paths that are likely to lead to scope creep, poor performance, or scalability issues.
The technical specification document is a companion document to your database schema and your HTML mock-ups, and it typically should include both the schema and mock-ups. It should restate any features mentioned in the requirements document and any functionality implied in the HTML mock-ups, such that the entire set of project requirements exists in the technical specification. Why? Because your developers—no matter how hard you try—will only begrudgingly read one document. You want it to be the technical specification.
A basic technical specification includes the following elements:
The pieces of a basic specification are straightforward and include the biggest section by far: the functional description. The functional description should be littered with screen shots from your HTML mock-ups and references to the database schema.
Essentially, this section should step through each major part of the application and describe, in plain language, every little thing the application will do. Just pick the first page of the application, paste in a screen shot, and start describing everything on this page.
The full database schema can appear at the end of the specification, in an appendix. For example, Microsoft SQL Server Management Studio includes a handy tool to visually define the primary-foreign key relationships between tables. Screenshots of these diagrams clearly convey how the schema supports the project's functionality.
Consider the entire life cycle of a feature by thinking through all of its implications. This helps you identify any potential “gotchas” that will impact the schedule, scope, and challenge of a task.
Some questions you might ask:
The single most important task in writing a technical specification is to ensure specificity.
The following is an extract from a technical specification for a web site project that involved a complex custom events registration system. This section describes an information box at the top of the user profile page, referencing the specific fields in the database where this information resides:
The user homepage for registered members includes a small information block at the top of the page and an events listing below. The information block displays
This next example is from the same project and describes the logic that defines what appears in an RSVP column of a table of upcoming events presented to a logged-in user:
The Status/RSVP column:
Congratulations! Due to a cancellation, you have been moved from the wait list to an attendee for [EVENT NAME] on [EVENT DATE AND TIME].
Login at http://example.org for complete event details.
The Status/RSVP button uses eligibility logic outlined in the Event Eligibility section to control for which events the member may register.
The detail in these examples may look excessive, but these questions need to be asked and answered before the project starts, as part of the requirements document (See “About Requirements” in Chapter 4). If they are not, then programmer hours will be spent fixing these issues after primary development is complete, when it is much more time-consuming to make changes.
The additional sections of your technical specification will likely be defined by the requirements of the project and might include sections like the following:
For a larger custom development project, it is helpful to talk a little about the application architecture:
The servers supporting the project will also impact development and should be stated clearly:
If your team has new members, clearly (and briefly) explain how your shop develops software. An experienced team will have made the mistakes that less-experienced programmers tend to make, and will avoid them. But you cannot assume that new members will have had the same experiences.
Finally, consider if there are any security implications in your application:
______________
2 Data imports are almost always harder than you expect. Protect your project budget by throwing a lot of detail and planning into the data import before development starts on any part of the application.
See the Appendix for some great additional reading on writing a technical specification. If you have time to read only one additional article, read Joel Spolsky's “Painless Functional Specifications.”
Your planning is done. By now you should have a strong sense of all of the documentation you need for your project, be it requirements documents, HTML mock-ups, wireframes, designs, technical specifications, or database schemas. It's now time—at long last!—to cash in all of your hard work and begin development.
In the next chapter, we cover everything you need to know to keep your sanity during the development phase. We start with a horror story about a developer going rogue. We cover guidance on how to keep your client in the loop, tips for writing professional e-mails, and easy ways to maintain documentation.
We go over the simple but powerful method of using checklists to maintain quality and show you how to avoid the crippling nature of no-win-scenario bugs. We wrap up the chapter by detailing how to conduct weekly developer meetings that keep your team happy and your project on track.
18.226.187.233