How to write a project Analysis or project brief? [closed]

Question

We are a small (15 ppl) webdevelopment/design company with around 8 fulltime LAMP developers. In order to reduce the amount of errors we make and to prevent our budgets overtaking our estimates i've introduced some sort of technical analysis of our projects before development kicks off. This is a no brainer for an application developer but in our sector (webdev) it seems less than common practice. Up until now we just received a small brief our project manager assembled (often less than one page) and jumped head first into development with some catastrophic budgetting failures as a result.

In order to tackle this problem i started reading on the subject, i've read CodeComplete2, Pragmatic Programmer and The Mythical Man-month. I think i've grabbed the concepts behind preparing and analysing a new project but i'm lacking practical examples. Does anyone know of an example technical analysis or extensive project brief that i can take a look at in order to better put the stuff i've read to practice? I'm a big fan of learn-by-example, no need to say that :)

Answer 1

Unfortunately most project scope documents are commercially protected so they can't be published, however I'm happy to pile down my experience of what makes a good one and I've included the sort of things I'd hope to see.

The main thing to remember is what you're trying to achieve - you're trying to get a common understanding between you and the client about what is happening. Bad estimates aren't just about the difference between what you thought it would take and what it did take, but also about what you thought you were going to deliver and what the client thought you were going to deliver.

One way of looking at documenting all this is so you're covered and if the client does come back and go "where's the reporting module" you can just point to the sentence that says "there will be no reporting module" but that's not really it. It's really about having that conversation at the beginning (where it can be constructive) rather than the end (where it's likely to be confrontational). Remember this if your project or account manager starts staying that too much detail sounds negative.

So, what should you include:

• High level description of what is being done - just a couple of paragraphs. It's really not going to provide any detail but it sets the scene. So in this section you say you're building an e-commerce site to sell widgets, that it's a B2C rather than B2B site, that the project covers the complete design and build of the site and so on. A couple of paragraphs at most.

• High level functional requirements - bullet points outlining the key features which will be built / designed. For each data entity included whether it's create, read, update and / or delete as this will help you to better understand the task. So include the ability to create/read/update/delete users, the ability to create, read and update orders, the ability to create/read/update/delete product categories, the ability to create/read/update/delete products including text, images and video.

• Non-functional requirements - another area where loads of stuff gets missed. Non-functional requirements include things like performance, user load, auditing, archive, security and so on. Reporting might fit in here - although it's really functional it's something which sort of gets forgotten as it's often something which supports the systems use rather than being a core part of it. If you're not doing something in a give area (e.g. there will be no audit trails) then state that clearly, perhaps in another section called...

• Out of Scope - Things will come up during discussions about whether something (a bit of functionality, an interface to another system) is or isn't included. Write these down! One of the key areas where scope fails in my experience is different recollections of these conversations and getting it on paper up front gets rid or much of that. This is another area where reporting can come in (they'll know they want reports but not what so it kind of drifts then you deliver and they ask where they are), but also user management (password reset?) and security.

• Assumptions - At this point during the project you're going to have insufficient information to come up with a really accurate estimate. That's OK, you can fill the gaps in yourself, so long as you make it clear that this is what you've done. So if you're making the assumption that they're providing you with corporate templates for laying things out then write that down. If you think they're providing the copy and images for everything, again write it down.

Other sections I'd consider including:

• Technical platform - if you think it's important describe the technical platform at a high level (in this case LAMP plus any other bits). In my experience this isn't an area where scope creed really occurs but it tends to be two minutes to do so it can't hurt.

• Interfaces to other systems - In my experience one the things which adds complexity to any project is things over which you do not have complete control, and one of the key areas this happens is interfaces to other systems. Where you're dealing with these it's always best to list the systems, the type of interface and what interactions are going to take place. So, if you're updating their stock system say you are, say it's a web service, say you'll be firing stock queries, updating stock levels and so on.

• Dependencies - Again, this is part of the outside of your control thing. If there are other parties contributing to the project (including the client), it can be best to list what you're expecting of them. Who is providing the copy, in what format (is it a nicely structured Excel file that can be easily imported or a million Word documents)? What about a test system for the third party application you're expected to interface with? When do you need these things?

Hope this helps.

Edit: I've dug out and slightly anonymised a couple of templates I used in my last job. They're internal (that is we were an internal team doing work within the company as opposed to a team doing work for another organisations) but the structure and principals are the same.

I've included a project mandate template which is pretty close to the sort of document you want:

http://seventeensix.tumblr.com/post/749062608/a-sample-project-mandate-template

and a specification template which might also have some bits you'll find useful:

http://seventeensix.tumblr.com/post/749077647/a-sample-specification-template

The project mandate one contains some real samples from one of the projects there (a very tedious financial systems reconciliation package), both contain structure and pointer as to what goes where with the odd example.

Answer 2

Those are all fine books. I might suggest also adding "Software Requirements 2" and "Peopleware: Productive Projects and Teams" (I haven't yet read Peopleware; it's been on my todo list for a while, I'm afraid.)

But I'm afraid there is no substitute for experience; if you pay attention to what your team has quoted in the past, what it actually took to deliver, and try to find the reasons why you were right or wrong for the pieces you were right or wrong on, you'll learn how to be better.

In my experience, it never hurts to try breaking down the large problem into smaller problems. Iterate. When you think you've finally got pieces that will take .5 to 1 programmer-day, then you're reaching the point where I have had the best success when estimating time.

Of course, you have to keep in mind the programmers working for you: Alice might code a shippable solution in half a day, Bob might take a day, and Charlie might take two days to get there, with an hour from Bob for code review. Knowing your programmer's strengths and weaknesses will also take experience.