Get Control! An Introduction to Process and Documentation Parts 1 - 5 - Connecting the Dots

Why Aren't There Any Graphics?

Using graphics on a wireframe undermines the purpose of the wireframe, which is to get both your client and yourself to truly consider the specific functional (not cosmetic) requirements of a page. Therefore, any colors, fonts, or graphics will serve as a distraction to the client, and will make it harder to keep them focused on the matter at hand. The cosmetic information is best left in a creative brief or other document so as not to disturb the discovery process that is so well facilitated by the wireframes.

A simple, unpolished look is generally best when it comes to wireframes. Keeping the wireframes slightly 'rough' demonstrates to the client that the document is not intended to look nice -- that it is a working, living document, a vehicle for important non-graphical information, and doesn't need to be dressed up.

To illustrate this point, let's imagine you're planning a Website that includes a 'news module' to allow the client to easily add/update/delete news stories and modify the way they appear on the homepage.

The initial homepage wireframe would show the basic elements of the page, including large blocks for repeated elements like 'persistent top navigation' or 'footer'. These frequently-used elements will be diagrammed on a single page of the wireframe document, and will simply be referred to in the other pages, similar to the way includes are used in HTML pages. The wireframe would show any ads, copy blocks, or other elements that should be included on the page, as seen in the following sample:

It seems simple enough, and it is -- until the client has a look at it and (hopefully) starts asking questions. Soon, additional pages of the wireframe document can be created and callouts can be used to document simple specifications. As the document will be signed off by the client, it's in your interests to get as much detail as possible into the callouts, ensure that everyone is clear on the project specifications, and that you are protected from potential misunderstandings.

If a 'news headline' page was to be created, it might be a good idea to document some of the character limits for headlines before development, to make sure that the specifications are acceptable to the client. The wireframe might look something like this:

Over a period of days or weeks, this document can continue to expand, to become a definitive part of the project's definition -- allowing the client, project manager, and developers to be precisely clear about the work to be performed. This provides the following benefits to the project:

1. It establishes names for each page in the site, making communication simpler throughout the project.


2. It provides a very clear, simple mechanism for clients to approve project specifications, which are easy to read, and difficult to misunderstand.


3. It helps to identify areas of confusion ('what happens when you click here', or 'I thought it would automatically sort by date', or 'shouldn't the article author appear on each page', etc.).


4. It provides a no-brainer way of accumulating notes and comments that relate to a single page -- if there are too many notes on a wireframe page, you simply add another page.


5. It contributes to the general documentation of the project, which makes for easier process and change order management, and better user acceptance at the end of the project. It's usually not worth wireframing every single page in the site, but once the main pages are wireframed, it's quite simple to cut/paste new wireframes and gain signoff on the majority of the pages.


6. It forces everyone involved with the project to take a good look at what they're creating, and what it will do. It makes everyone address problems such as 'what happens if you click here, is it a pop-up or just a new page?'


7. It helps clients to consider functional requirements without the distraction of visual elements like colors and fonts, saving valuable time in meetings and ensuring that the client actually understands what they're getting.


8. It provides one of the best ways to take a project plan and give it to a team of developers. It's easy to understand, and helps everyone to get up to speed quickly, saving precious development dollars.

The Technical Specifications Document

The technical requirements document is similar to the functional requirements document, but answers a different question for a different audience. This document should answer the question, How Does It Work?, and, unlike the functional documents, should be limited to answering that question in a manner that would be useful to technical personal or other IT providers.

Because the 'tech spec' is geared towards a technical reader and contains no functional concepts that need to be approved or understood by a non-technical audience, the language can be highly technical in nature, and should contain any kind of information that is deemed useful. Typical technical specifications include information such as:

• Database Models
• Class diagrams or architectural plans
• Platform specifics including OS/language/compilation details
• Load Balancing and Migration Info
• Use of third party components or objects
• Licensing issues, when related to the above topics
• Performance expectations and limitations
• Integration techniques and i/o mappings
• Backup and disaster recovery planning

As you can see, the technical documentation says little about what an application actually does. It's focused on how it does what it does, what makes it work, and sometimes why those particular solutions were chosen.

By separating the functional and technical documents, you'll make your life easier in two ways. First, you need only collaborate with the interested parties during the documentation phase. In other words, you only need to talk about the functional specification with the people who are actually interested in the functionality, rather than having to deal with uninterested IT people who were asked to approve the documentation.

Second, you can ask your client to have specific individuals sign-off on each particular document. I like to have a high-level (but involved) person at the client organization sign off the functional specification, but I always seek the most technically savvy person I can find to sign off the technical specification. This approach to signoff creates the most comfortable outcome possible, as the people who will best understand the different documents are the people who take responsibility for their contents.

The Rest: Paradigms, Schedules, Workflow, Testing and Milestones

…Plus Use Cases and Test Cases and Deployment Plans and Integration Mappings, and Progress Reports, and Risk Assessment Documents, and User Acceptance Forms…

Depending on which process system, methodology, or personal style you use in your business, an incredible variety of documents can be used to capture and clarify information that's not found in the functional or technical specifications documents.

Every project is different, and the critical information required to complete different projects can vary greatly. It's important to consider which documents you will generate and seek to have signed off during the course of a project. The functional and technical specifications are highly targeted and concise, because they are critical-path tools for success. However, most other information can successfully be documented using whatever format seems most appropriate for the time and scenario.

Typical documents include:

1. The Contract - This mandatory document is extremely useful and sets the tone for the entire engagement.
2. Project Scope and Overview Document - This document precedes the formal functional documentation, and gives developers a chance to demonstrate that they understand the overall parameters of the project, its scope, and its general requirements. The document may be created in any format, and can frequently be evolved into a specification document once the engagement begins. This is a very handy way to do a 'temperature check' on a client before issuing a bid.
3. Project Schedule - All clients want them, yet most vendors hate making them. Gantt charts (such as the charts generated by Microsoft Project) look great, but are quite a bit of work to keep updated. One effective approach is to block out how many days each large phase will take, then create a 'current target date' by adding up the days and projecting the date into the future. If the schedule changes, simply send the client an email with the new 'current target date'. This method also helps to maintain an understanding that both the client and the vendor are jointly responsible for the date.
4. Workflow, Roles, & Responsibilities - In some projects, it can really help to establish the roles and responsibilities early on. This is particularly true when working with a client who is inexperienced with Web development. Try to explain to your clients who you'll need to communicate with, what kinds of meetings, email, and correspondence they should expect, and how much time you feel should be allocated to make the project a success.
5. Phases and Milestones - In addition to providing a coherent schedule by which you can be paid, the phases and milestones document can help the client understand what will be happening and in what sequence. In addition, it's useful to define the milestones by detailing what the client can expect from an alpha release, beta version, and testing period, for example.
6. Creative and Technical Brief - Used to ensure that the general direction is correct prior to doing creative or technical work, these documents can be huge time savers. A few pages of information to describe, for example, the general creative aspects of a Website including comparison sites, fonts, colors, recommendations, and navigation, can have a huge impact on later work.

Why write a brief? The purpose of the brief is to get the major points of the technical/creative effort on paper so that the client can review them before you invest a large amount of time writing lengthy requirements documentation. By getting a sign-off on your brief, you've confirmed with the client that you are going in the right direction, and are less likely to miss the target. This approach is invaluable when working on a very large project, but is probably not required for smaller ones.

There are so many document types that it's impossible to list them all here. Your success will be ensured by selecting the document trail that is relevant, useful, and practical. You might find yourself creating your own formats or document types, or repurposing the same documents over and over again. Either way, it is an excellent practice to establish a document trail early in the project and to share your plan with the client.