Project Documentation and Specifications: Why they matter

Over the course of my career I’ve been exposed to several projects, ones where the project was explicitly described and documented utilizing preformatted corporate required templates, to projects who’s general conception was only documented on a yellow legal pad, or on a whiteboard. However, whatever the initial kickoff of a project is (the corporate laid out description, or the notes from a whiteboard) without proper documentation the project can become unmanageable.
As an analogy, imagine that you need new tires on your vehicle. You could easily drop your car off at the nearest garage, give them the keys and tell them you need tires. Without going through what your budget, driving style, or appearance preferences are; when you go to pick up your car you might be surprised at the bill, and even more surprised when your car has whitewall tires, and slides when it rains.
Similarly, if a developer is working on a project and someone generically asks for a report (without documenting what fields are needed, or how the report is to be grouped, or fields need summaries). The developer is either going to have to make a best judgement on the report’s fields and content; or will need to spend several cycles going back and forth with the users to determine what needs to be developed.
However, in both cases (tires or reports); if documented specifications were set out at the onset. The resulting products won’t be a shock, or need to be re-done multiple times to get to the final product.
Specs and documentation are like flossing: everyone knows they should be writing them, but nobody does.
Failing to write a detailed specification is the single biggest unnecessary risk taken in a software project. Teams that dive into estimating a project, or even start coding without a detailed spec tend to think they’re being proactive, or are trying to fast track a project. However, they’re not. Projects that are undertaken without having an overall project plan, which describes the main functionality and risks involved with certain architectural decisions will lead to code that is piecemealed together as items arise, and can lead to issues in production that were not thought out completely.
The most important function of a project document and specifications is to assist in designing the program. Even if a single developer is working on a project by themselves, the act of writing the documentation and project specifications – describing how the program works in minute detail – helps to actually design the project and understand how, and were, all the pieces and parts fit in and interact overall.
Let’s imagine two separate project teams working off a set of simple requirements. Both are required to add additional functionality to an existing product and code base to add Administrative Functionality, and a data import/export functionality. Both teams are provided an excel spreadsheet with the request to add the two pieces of functionality.
Team A:
Takes the excel spreadsheet and begins coding. In 2 weeks they develop an admin screen that provides direct table access to all the tables needed in the application, and a corresponding Import/Export function for each table.
While the programming team is fairly quick in developing these pieces of functionality – which do match what was originally asked for, upon presenting the changes to the users it is determined that additional modifications to how this functionality actually needs to work. Team A then needs to re-work the solution for another 2.5 weeks, and causes a delay in releasing the software to the users. In an effort now to catch up, corners are cut to meet deadlines, and the solution deployed is somewhat temperamental to use.
Team B:

Is provided the same excel spreadsheet. However, upon receiving these requests Team B starts documenting the request and how they are to be tied within the application. As they do so they start asking questions like:

• Which users will be limited to have Administrative access?
• Which sections of the application need Administrative functionality?
• What data will need to be required to be inserted/exported?
• Who needs access to the Import/Export functionality?

All these new questions are discussed further with the user team and documented into the product documentation and specifications. After a day of fine tuning and documenting these changes Team B then spends 2 weeks developing the enhancements.

When the users are presented with the enhancements, they know exactly what to expect from the application and how to test the application correctly before deploying it to production.

While a very simplistic example in our story, the moral is that when you design a project utilizing a description of what needs to be accomplished, it only takes a few minutes or hours to think about different possibilities, risks and issues in the overall design of a request.
However, when you begin your design and start coding without taking the possibilities, risks and issues into account it might take even more time to change the existing code that was started without the level of detail that was needed at the beginning of the project.
Additionally, no one is going to feel bad changing the requirements in the product documentation, however, a programmer who has spent the two weeks coding from the original limited specs might be frustrated, or under a time crunch, to now change or add additional functionality that was not included in the beginning.
The second big reason to write detailed project documentation and specifications is to save time communicating.
When you write out a detailed project document with specifications you should only have to communicate how the project is supposed to work once, and that is captured in the main product documentation. Everyone on the team would have access to the project documentation and specifications (they aren’t it multiple documents, someone’s email, or lost in side meetings or hallway conversations).
Also, I should stress that EVERYONE, has access to the product documentation and specifications. The Users requesting the project have access to it to verify that is exactly what they asked for. The PM can gauge the status of a project based on the specs defined and what has been delivered. The development staff has access to it so they know how to code the solution. The QA/ UAT Team has access to it so they know, and can test, how the project is supposed to work. Trainers know how to write the documentation, or train people on how the project should work. And lastly, the next revision to the project now has documentation of what was done to the project for future iterations and subsequent project teams.
When you don’t have project documentation and a spec, all this communication still happens, because it has to, but it happens ad hoc. The PM needs to root though emails, documents, and notes taken during meetings since they aren’t al housed in a central location. The QA/UAT people fool around with the progam willy-nilly, and then when something looks odd, they go and interrupt the programmers to ask them another question about how the project is supposed to work. Besides ruining the programmers productivity, the programmers tend to give the answer that corresponds to what they wrote in the code, rather than the “right answer” of what the spec originally called for. So the QA/UAT team are really testing the program against what the programmer coded rather than against the original design which should be in the project documents and specification and be considered the baseline for QA/UAT to test against.
Also when you don’t have project documentation and a spec, trainer/technical writers don’t usually have the ability to ask the programmers how something is actually supposed to work. And users might receive incorrect instructions on how to utilize the project because the trainer, or even the users interpret how to use the project differently than how the programmer developed the project, or how the specs intended the routine to work.
The number 3 reason to have detailed project documentation and a spec is that without a detailed spec its impossible to schedule the project. As stated above without project documentation and a spec you run the risk of re-work, and delays in figuring out where the users meant one thing, the programmers coded it a different way, etc, etc. Yes you can do your best estimation of this task will take 4 hours, this one 8 hours, etc. But if you don’t have project documentation with detailed specs – you also need to take into account the amount of rework or meetings that need to occur to fine tune the details after coding has started.
Writing a spec is a great way to nail down design decisions, large and small that evolve as projects are developed. One must also realize that the project documents and spec aren’t written in stone. If during the design and coding something comes up that alters major functionality; the spec is referred to and modified accordingly during the course of a project. Or for example if your building a new website and one of the features required is that a user needs to be emailed a password reminder if they forget their password. Assigned items such as – “the project sponsor will provide the verbiage for the password reminder” can be listed in the project documentation or specs and all parties will know that at some point the project sponsor will provide the actual verbiage. And the Project Manager will know that at some point during development the project sponsor will need to provide the final verbiage. However, during development the programmer will know that this text might change at some time; and when the project sponsor provides the verbiage the project documentation will be updated. Otherwise, the developer could add some generic text to the message until the verbiage is finalized.
Now while you now see the reasons why project documentation and specs are important. The next thing to clarify is that is the difference between Functional Specifications and Technical Specifications and why you may very well need to create both of these specs.
People get these mixed up. I don’t know if there is any standard definition for either but in my experience this is how I’ve grown to define them from experience:

Functional Spec – Describes how a product will work entirely from the user’s or business sponsors perspective. It doesn’t care what technology is used or how it is implemented. Its main focus is on the project features. It specifies screens, menus, dialogs and so on. It can include mock ups of what the screens will look like, or include examples of what the screens look like at the end of the project. If there are any calculations/algorithms on how to calculate specific items – they should be spelled out here as well.

Technical Specification – Describes the internal implementation of the project. It talks about specific technologies, data structures, database models, objects, tools, classes, etc. These specs should be thought of the base blueprints for what needs to be built by a technical team. Technical specs are also important if you are sending the project to an offshore project team that might not have immediate access to ask questions as they come up, or for future programmers that might want to know how certain architectural decisions were made curing previous implementations of the project.

When you design a project, the most important thing to do is to explain and specify the user experience – which is the basis of the Functional Spec. What are the screen, how do they work, what do they do. A user or business sponsor isn’t going to care what classes were defined to develop the project, and might stick a technical specification in the drawer to collect dust. But, they will be critical in looking at the functional specifications to make sure from a day to day business operations perspective what is described will meet their needs.
However, the technical spec is important to the technical team who is developing the project. As mentioned above it is their blueprints for how they are going to build the application. There have been several times in my career where taking the time to write some basic technical specifications for myself on a project, I can start to identify decisions that need to be taken into consideration when building an application that weren’t initially discussed in the design. Or you may come to the realization that certain items have to be built, provided, or decided on before a section of the project is started. Otherwise, you’ll be developing something that might not be what the user was specifically looking for.
So, why don’t people write specs? It’s not to save time, because it doesn’t. I think it’s because so many people don’t like to write and rely on describing things over the phone or during a meeting which can easily be forgotten or misinterpreted during the execution of a project. How many times have you had a project and heard “well that’s not really what we described” or “well I mentioned it to you in our last meeting”. If decisions, and modifications during meetings, are modified during the course of the project. If you have the project documented and updates noted over the course of the project it helps all parties associated with being on the same page. Without a comprehensive set of documentation, projects can easily de-evolve into the classic tire swing meme of how a project is interpreted and executed.