Briefing Developers

For some time now, I’ve been meaning to write a post on “briefing developers properly”. The difficulty I’ve had is articulating it in such a way that it provides some real tangible advice that can be of immediate use to Technical Leads and Project Managers. The more I think about it, the more I realise I could write an entire book on the subject. There isn’t simply a one-size fits all Developer Briefing Template.doc that you simply fill in the blanks.

Many attributes affect which approach you use to brief a developer. Project type, project size, team size, and schedule are all attributes you need to think about when considering the most appropriate approach. For example, a small Flash based multimedia project would probably be best suited to a simple story board. A web site should have a site map as a minimum. A web application could require a more detailed work package incorporating UML.

What ever approach you take here’s some key points to consider when writing a brief:

• A verbal brief isn’t a brief. It must be in some kind of a written form.


• Piecing together the brief from a large email thread is the wrong type of written brief!


• Complementing the written brief with verbal communication is acceptable.


• Get the developer to play back the brief to you to give you the confidence they’ve understood it.


• Don’t be too prescriptive in the brief as you still want developers to use their expertise in coming up with solutions.


• Reduce the risk of over-engineering or misinterpretation of specs by putting extra effort into the test & acceptance criteria, and review their work regularly.


• Don’t just give them the document to get on with. Step them through it and get them to explain it to you.


• Don’t assume that something that is obvious to you is obvious to them. Explain everything, even if you risk insulting their intelligence.


• Keep documentation lightweight. Remember, “a document isn’t finished when you can’t think of anything else to put in it, it’s finished when you can’t take anything else out of it.” (Steve McConnell).


• Avoid writing a paragraph containing multiple business rules that may result in some rules becoming overlooked. Separate out each business rule into an itemised list that can be ticked off when completed.


• Pull together a work package that not only contains the brief, but also contains any assets or test data the developer needs to complete the work.


• Get the developer to provide you with a work breakdown structure for the task at hand, along with estimates for each task. When the developer goes through this exercise it shows they’ve really thought about what they’ve got to do.
  

Test & Acceptance Criteria
I can’t emphasise enough how important it is to define test & acceptance criteria for the developer. You can do this in a number of ways but I tend to generate some test data for “input” into the system and specify how it should result in its “output” state. If you do have a test team, get them to contribute to this section.

Your T&A criteria should exercise the non-functional requirements as well as the functional requirements. So, if you’ve specified 100,000 records as the warrantable limit of your system then you need to specify this in the T&A. You should also provide this test dataset in the work package for the developer.

Work Packages
In many organisations I’ve worked for, it’s very rare for a developer to do everything in the software lifecycle themselves. The organisations are usually made up of teams of Business Analysts, Graphic Designers, Producers, PM’s, Developers, and Testers. This results in a collection of documents looking at the project from different perspectives that the developers have to implement.

My personal preference when briefing developers is to create what I call a Work Package. This work package pulls together the relevant sections from the collection of documentation to deliver a specific piece of functionality. The following diagram should give you some ideas as to what could be included in a work package:


I often get asked how big a work package should be. This obviously depends on the size of the project, but from the point at which the developer starts the work package to the point where it’s finished (see previous post on what is classed as finished!), should be a minimum of 1 week. I’ve written many work packages that take 20-30 days to complete so there are no strict guidelines on how big it should be. I have found though that writing a detailed work package for small tasks of a few hours simply doesn’t work. Quite often in these situations I find a whiteboard or flipchart perfectly adequate, but the important point is that it’s being written down.