Documents for Managing a Technical Project

by John H
12 minutes

Documents Every Technical Project Should contain

I've worked in many places and I've consistently been let down by how technical production has been handled. Most managers just don't seem to have the technical chops to handle a large scale digital product. I want to make it clear that I'm not being critical of the manager because they don't know or understand all of the technologies required for the project - that isn't my issue. The issue is that these manager don't have the project management skills necessary to handle a technical project.

Anyone who has taken a project management course should know words like project scope, or project creep. It's possible that they might know how to make a flow chart, or *gasp even a Gantt chart. Even a bad project manager might even be able to flesh out a mediocre Creative Brief. But as developers, we need more.

Why are developers so cranky? The biggest complaint I hear from other developers is that their manager don't give them enough information to complete a job properly. There are always some hidden requirement or some forgotten, yet important, detail. Many times important logic is not defined and decisions that affect production is left ambiguous. These problems all lead to project creep, and wasted resources and ultimately unhappy developers. It is unprofessional and inconsiderate of the job that employees do. So how do we avoid this?

These are Non-technical Documents Anyone should be able to pickup these project management documents and understand what is going on. Sure the product is technical, but the actions and responsibilities should be easily understood. If a project manager does their job right, anyone should be able to lead the team to success. Maybe that's why I'm so surprised at how poorly projects get handled.

The Documents

Creative Brief One of the most prevalent documents I've seen in marketing departments and agencies is the Creative Brief. This document usually holds high level details - maybe a little history, or project background. It might have some details about the end user or the target of the project. It may have some budgetary considerations, information about deliverables, and possibly even a drop date or two. Creative briefs are not created equal. Some have lots of details and some are vague and so high level that you don't even know what you are looking at. Creative briefs are good - but they are hardly enough.

Wireframes A wireframe are nothing more than a visual layout of screen elements. They are typically devoid of any graphical choices - things like colors and images are left out. Wireframes are great because it can give a developer a better sense of the end product. It's doubtful that they have every logical consideration defined in the wireframe, but it can help examine the product from a more tangible direction. I think managers should complete a wireframe because it helps nontechnical personnel flesh out the product, and better understand the relationships between the requirements and product interface.

Another big reason that a manager should use wireframes is because it is a fast deliverable that a client can sign off on. Since wireframes don't have graphical elements, it usually helps move a project's functional requirements forward. Additionally if a client signs off on a wireframe it can define a project milestone that should help keep a project on schedule.

Where wireframes fall short is when a product has a complex backend, such as a complex database structure or complicated MVC setup. This is where the business logic hits the development logic; it is where we see the backend get connected and integrated with the front end. The good thing about a wireframe is that they are fast to make and typically don't require much effort, and they can help diagnose problems architectural issues faster allowing them to be addressed.

Flow Charts and Tree Diagrams I rarely receive these - but I'm sure that some dev teams might get these project assets. Flow charts are fantastic for user interfaces, or any situation that could use a visual graphic to displace logical process flow. I've never gotten one from a project manager - and I've never had a manager assign that task - but they should be included in any large scale project. Flow charts are a visual representation of processes.  They can help to define a process. This is really important when a products' user interfaces are important. They are useful for developers because they can highlight logic and considerations that end up int he core logic the developers build.  A developer takes a flow chart and converts it to a series of "If ... else " statements that make up the programs.

A flow chart should be created by your UI experts - If you don't have a UI expert then your graphic designers might need to be tasked with this deliverable. This is important because the alternative is your developers building the User interfaces and that typically doesn't end well - it could also lead to reworking and rewrites. This makes unhappy developers.

Tree diagrams give a visual layout of sites and products. They basically look like a site map. These can be valuable at showing what content and pages might be expected. It can be a good deliverable for a client to sign off on as well. Tree diagrams provide managers with a check list that can help them focus on what needs attention.

Tree diagrams, flow charts and wireframes are all pieces that should help a team work towards a final concept without expending resources -

  • They are fast and easy to make
  • Define product layouts
  • Define expectations
  • Flesh out final project
  • Provide project milestones
  • Reign in Project Scope and eliminate creep

Final Graphics Developers will get finalized assets 15 mins before launch. It never fails. A project could be 2 years in the making, but a Dev will only get final graphics on the day of launch. I don't know why project manager can't get this right. They delegate the work, they wrote down the assets in their creative briefs, they might have even made a note on their wireframe about the inclusion of some finalized graphic, but for some reason they can never get final, approved graphics with any lead room what so ever. Why is this?

Deliverables List Every piece that is expected will be in this list. Every expectation, every goal, everything that will be delivered will be here. Imagine this as a project final checklist.

Needs Analysis That deliverables list you just made - what do you need to make it a reality? A needs analysis is a break down of all of the pieces that are going to built and what resources are necessary to complete that deliverable. In a needs analysis for a website there might be things like, domain, approved copy, graphics, database etc. It is just a way to put every single thing that will be needed to build out your project. This is a great exercise because it makes you think of everything you NEED in order to reach your goal. If you your Creative Brief is high level, then the needs analysis is low level. Not only does this paper provide you an outline of every deliverable, but it also gives you a basic check list for your project. Got the domain? Check. Got the database setup? Check. Got the initial build setup on a dev system? Nope - okay so what are the pieces we need in order to finish that deliverable up. Oh you need content? I can get that. You need an admin account with credentials - Okay - let's focus on that.

This step can be so helpful, because many of these things a developer will have to set up anyways, but if they need a specific account for an admin or a manager, then why not have them set up the correct accounts initially. This saves time, effort, and hair. So much time is wasted by developers getting resources that non-developers could acquire.

Task Analysis See that list of deliverables - now let's create a list of actions and task assignments to complete that project. Every pieces of a needs analysis should have a task assigned to it as well as who is handling it. You could take it a step further and put a time expectation, budget expectation and any other information you can suss out in it as well. Most importantly though is identifying the tasks and delegating responsibility. For example if a need of your project is "Domain" Then the task would be "Acquire Domain" and then delegate it to "John". What you will ultimately have at the end of the Needs and Task Analysis is a project, broken down in to singular tasks with assignments of those tasks.

Gantt Chart Take your Needs Analysis and your Task Analysis and put them into a schedule; that is the Gantt Chart in a nutshell.

Probably the most ambitious of all of the things talked about in this article is the Gantt Chart. It isn't necessarily as valuable to a working developer as it is to the manager themselves, however it is a great tool for helping everyone stay on the same page, as well as track dependencies.

What is a Gantt Chart? It's a staple of project management. Many project management softwares will spit them out or provide Gantt views. For those of you who don't know what they are - it is simply a schedule of all tasks for the project. For each task of a project there will be a start date and an expected completion date. What it provides is a daily summary of tasks that are being worked on and expected dates of their completion. What it also does is give a visual guide of dependencies. If part A has to be complete before part B can be started, then it can help a project manager expedite work on part A. Therefore if a date gets shifted then it help the manager see if other task's dates need to be adjusted. Gantt charts can be laborious to create, hence why they are used so infrequently. Also it can be hard to actually set down and break a project into tasks and pieces - but that's why they hired a project manager, right?

Finalized Approved Assets In a perfect world, a developer would only work with finalized and approved assets. This means no graphics would change after they are installed. No copy would change after launch. No accounts would have to be reset, or withdrawn. Everything would be launched the way it is meant to be. I know this isn't realistic, but it is a goal to shoot for, and ultimately it should be project manager's job to cut down on rework - work that has to be again, because content was wrong - graphics weren't approved and someone dropped the ball. I've worked as a graphic designer - and when something is sent to print, it's out of my hands - if you signed off on something, the only way to correct the issue is to rerun the job, which costs more money. In the web world things are a little more murky. Things can be fixed with little regard to cost, and as a result proofing and editing can be a little more lax. Mistakes are made, and as a result developers end up making corrections that would never have happened if there was a level of finality present like there is with print. So let's make an effort to limit rework.

Conclusion Maybe your company gets by without any of these documents. Maybe this is all just busy work that makes no difference to your project. Well all I can say is that you are in the minority - or maybe your projects aren't complex enough. I've been on teams that chewed through 500K budget and didn't accomplish anything. I've been on projects that have blown through their development budgets with absolutely nothing to show for it, and a product that is still so undeveloped it's useless. In every one of those instances there were too many chefs in the kitchen and noone leading the group. These documents help define expectation, assign responsibility, and streamline production. A manager's role should be to increase productivity - that might mean shoveling coal into the engine, or getting approved content to your developer. In both cases its about getting to your destination.