ROYL DEV BLOG

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:

  • Technologies
    • Include the CMS and version, requirements around the underlying programming languages and versions, operating system requirements, search technologies, etc.
  • Services
    • A list of 3rd party services we are integrating with, or utilizing in some fashion. Usually this list implies we are interacting with an API, or in need of some sort of XML feed, or something similar.
  • Web Hosting Partner
    • Information around the web host. Include information around backups, support, and redundancies here.
  • Browser Support
    • Which browsers the site must support. Include mobile devices as well.
  • Performance
    • Include specific requirements around performance metrics. For example, "time to first byte must be between 200-400ms".
    • If you are using New Relic to monitor performance include the key metrics here.
    • Include and expand on specific caching requirements, asset minification, caching, CDNs, etc.!

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:

  • Features
    • Describe the unique functionality of the site here. Describe how 3rd party integration's will work. Describe requirements around backend functionality. Include SEO requirements, schema markup, social sharing and integration. Does the site have an events calendar? Describe in detail the functions of the calendar.
    • In project management terms, each feature here would correspond with a "component" in Jira (for example), that would be estimated, prioritized, and groomed until it was ready to be developed. Conversely, any component would have a corresponding set of requirements.
  • Usability
    • Requirements around usability. For example, ADA requirements. Does the site have to meet any web accessibility standards? Should content be made available in multiple formats? Should the entire site be navigable via keyboard?
  • Use Cases & Work Flows
    • Use this area to define expected workflows, such as content moderation, user sign up process, or complex form interactions.
  • Legal
    • Cookie Notifications.
    • Compliance review and process by a governing body.
    • PII or HIPAA requirements.

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.