For a long time before any software is purchased or code written a software or change management project only exists as a series of documents which lay out what the project is hoping to achieve – as such for CRM projects Consultants and Project Managers will have to write a good number of documents throughout a project.
Throughout my time I have a seen a great deal of these documents and come across a common problem in seeing documents that fail to describe what the client is looking for at that point in a project – often when picking up an existing project I am presented with a weighty tome that is the only document which describes what on earth as go before or is hoping to happen in the future; which is fine for Consultants or other people heavily involved in the project but at some point the senior management (and the people controlling the purse-strings!) will quite rightly ask ‘what are we getting for our investment?’ only to be presented with a 300 page document. It is kind of the equivalent of a meeting where someone is asked a question and responds by talking non-stop for 20 minutes as way of an answer.
No one enjoys reading weighty project documents or long technical answers, however we can make these documents (which are in affect an attempt to communicate like any other) more relevant to the intended reader and hope to convey the information we need to convey at that point in the project. Towards achieving this I tend to think back to the traditional English-Essay style of writing: FAP, Form, Audience, Purpose.
Form – what is the format of the document? The general tone and writing style of the document, should the document consist of smaller bullet points that each convey a separate point (a la a requirements catalogue) or should the document be more human readable with strong sentence structures and possible narrative.
Audience – who is the document aimed at? Does the Decision Maker of a company who is concerned about whether a project will justify the investment (particularly to Shareholders or the Finance Director) want to read through the low-level detail of Solution Design aimed at the solution developers, in most cases he or she will want a document more tailored to their high-level concerns. Documents produced throughout a project should know their intended audiences(s and be written accordingly.
Purpose – what is the document hoping to achieve? Is there any point in a document detailing a low-level requirements of a software system when the proposed benefits of the system have yet to be confirmed, each document produced throughout a project should have a set of purposes which are ideally set out clearly as the foreword to the document itself.
As an example, applying this to the different phases of a traditional Waterfall project we can look at the different documentation we may produce at each phase and how we can keep each of the documents ‘on-track’ to be informative and relevant to the intended audience.
NOTE: This example uses the example of Waterfall style Project Stages that fits into my usual PRINCE2 model of thinking – obviously these stages would vary for other Agile or SureStep methodologies, and also may vary or merge depending on the size of different projects.
1. Scoping Document
I would see this as a statement of intent document that outlines the broad problems that the client is looking to solve, the scope of these problems and a very high-level outline of how these problems may be solved with (guess-)estimated costs – often acting as the Project Initiation Document for potential future phases of the project.
The document should be readable and be kept as brief as possible to give the reader a good feel of the potential project without including low-level detail.
Based upon: Short schedule of workshop sessions with small groups or individuals who form stakeholders, key decision makers and management for each of the Business Areas or Processes involved.
Expected Content: Discussion of each business area or process that is expected to be included within the project with a set of Business Requirements that may act as the success criteria of the project.
Purpose: To provide the client with a view of the potential project and the intended business benefits against estimated costs – such that the client can determine whether to proceed with the project.
2. Functional Document
The Functional Document should then take the areas identified by the earlier Scoping exercise and detail the Business Requirements in further detail alongside the Solution Requirements that are required by the solution to achieve these
Based upon: Longer Workshop Schedule involving the Key Users and the Front-line staff involved with each of the Process Areas.
Expected Content: Detailed focus on each business area or process with a description or diagram detailing the Processes involved and how the potential solution will affect or change these Processes, alongside a full Requirements Catalogue that may act as the success criteria of the solution. Often we would expect the Functional Document to contain a section that details the expected User Experience for the end-users as a more practical vision of the intended Business Process.
Purpose: To provide the client with full functional idea of how the solution will meet the aims laid out in the Scoping Document and how the proposed solution will operate for the end users.
3. Solution Design Document
The Solution Design Document then aims to take the Functional Document into the territory of explaining how the identified requirements will be implemented and the how the technologies (typically identified in the Scoping Phase or Functional Phase so that costs and other implications are identified well in advance) will mesh together to form the final solution.
Based upon: The Solution Requirements and discussion with the Functional Consultant responsible for the earlier Functional Document.
Expected Content: Specific Solution Design for how each of the requirements will be implemented, the skills required for the implementation that can then form a series of Work Packages and possible Development Phases.
Purpose: To act as a focal point for both the client and implementation team to understand how the requirements outlined in the earlier Functional Document will be implemented and to give further detail on how the solution will operate for the end-users.
4. Technical Design Documents
The Technical Design Documents then detail individual technical areas of the project to communicate the design from architect to developer.
Based upon: The Solution Design for each the Requirements and the knowledge of how these can be implemented using the technologies chosen.
Expected Content: The envisaged intention for how the Development piece will be implemented and the expected end point for the completed development and intended Test Plan.
Purpose: To communicate or document one of the technical work packages to the Development and Test Team.
The overarching purpose here to define each of the Project Documentation to ensure that each is fit for purpose and not overlapping each other (unless internationally) to give documents that the intended audience struggles to interpret. This set of thoughts largely comes from two recent examples of projects that I worked upon:
– An existing project that we picked up from another Consultancy where the only project documentation consisted of a 400-page document that ranged from general information about the project in-between lengthy listings of every field, development code and screenshots; the result being that the senior management outside of the project had little idea of the project’s purpose and why they should invest any further money into the project. This sense of confusion about the project had been communicated down and so the project was largely a failure as a result – hence our company being called to initiate a Phase 2 which was more a case of re-doing Phase 1.
– A project bid where we did a series of initial scoping workshops to produce a scoping document that the client would use to present to their board as a steering document. We (for all sorts of reasons, some of them ours and some of them forced about us) blurred the line between Scoping Document and Functional/Design Document to produce a 200-page behemoth of a document which blended high-level overview with low-level technical detail, we did not win the deal..
This is a slightly dangerous article to post on a blog, as well as the aim of a ‘good document’ being very subjective from one person to the next, obviously all of these points apply to writing a post here as well – with the slight ‘get-out-jail’ card in that a blog is free and as such a blog’s audience and purpose can be less well-defined, however you still have a format for your writing, an idea of who you are writing for, and a purpose to each posting that you are looking to communicate. I’ll have to let you decide whether this blog meets the idea of good document writing as laid out here!
