Technical Documentation for a Web Development Project

Working on a large web development project requires that you have clear direction and good technical documentation. The designer needs to understand the functional requirements and the data model in order to deliver a successful design. The themer need to understand the UI/UX spec in order to deliver accurate and functional markup. The developers need to understand the functional requirements and data model in order to build out the CMS backend. Creating these documents, as a team, will help guide the project to success.

The documents described below narrow the scope of the project, each one focusing deeper and deeper on each aspect of the project. The process of defining the scope in the lifecycle of a project follows this informational flow; SOW -> Technical Requirements -> Functional Requirements -> Data Model -> Sitemap -> UI/UX Specifications -> QA Plan. Each document is a closer view of the scope of the project. The SOW is very high level while the UI/UX spec is in the weeds. I am primarily a web developer and web architect so I will focus on the architects/developers needs around these documents.

Technical Requirements

The technical requirements document is short and sweet. It is the "non functional" requirements of the project. This document outlines the technologies and services upon which the system will be built. Common sections in this doc include:

Functional Requirements

The functional requirements document is the meat of the actual website. The functional requirements document describes the actual functions of the site. I tend to organize this document into the following:

Data Modeling

The data model is often overlooked and just sorta dealt with. A designer will often times dictate the data model through their design. This will put impossible and/or expensive constraints on the developer. The data model informs design.

The data model document is a diagram that clearly illustrates how the data in the system is organized, how it is categorized, how it is searched, and how the data relates to each other. You should include all of the fields for each content type that will be required. This might be one of the most important documents. It will have a large impact on all teams.

Sitemap

This is a client facing document that shows a sites overall organization, design goals, and information architecture strategy.

UI/UX Specifications

The UI/UX Specification document is a detailed document that explains how a component should operate from a UI/UX perspective. For example describing the behavior of a header. You would tell the developer that on page load the header will be transparent, when a user starts to scroll the header will animate to become opaque. The animation should happen in 200ms. As a user scrolls the header will be fixed to the top of the page. It is extremely helpful to include diagrams, flowcharts, and screenshots to illustrate the described behaviors.

Remember that you are not telling the developer how to do something, you are telling them what it must do.

Summary

To summarize, each document informs the next, and each document helps clarify and define scope which should make estimation and timeline planning more accurate for the project manager, reduces the amount of assumptions a developer has to make, and defines some guardrails for creative. The project manager ultimately "owns" these documents, but it is absolutely a collaborative effort in creating them. In my perfect world it reduces guesswork and limits the amount of "oh shit" moments at the end of the project.