Finding and Structuring the Content
The content of a project document resides in the minds of the project team members, who are generally a group of individuals who represent specific stakeholders: those who will provide information to a process, those who will consume the output, and those who will do the hands-on development/maintenance work to implement and perpetuate it.
Your Role
As the author of project documentation, your function is to draw the information out of the team members, enable them to express themselves with clarity and precision, and help to arrive at a consensus.
Of critical importance: the documentation author is not expressing his own ideas or serving his own agenda - he should be helping others to express and achieve theirs. (EN: this is an ideal situation, though the author should consider that sometimes, the task of documentation is assigned to a member of a specific faction, as a method of gaining control over the project.)
Building Rapport
A key task is to develop rapport with project team members to overcome barriers to participation and cooperation among team members. The author indicates that "there are many books that provide excellent guidance," then makes only a few basic suggestions:
- Encourage profuse input. Results are better if you begin with too much information and have to weed out the irrelevant rather than too little and have to go hunting.
- Start in the Clouds. Begin with gathering general information, and gather more specific details later. If you go into detail too early, you may be lost in the trees.
- Be Informal. A rigorous and formal process provides a great deal of latitude; being overly formal stifles input.
- Repeat and Confirm. As you work, take notes on what people say, then repeat it back to them, in different words, to make sure you understand their meaning.
- Avoid Meetings. People are more forthcoming and expressive when contacted as individuals or in small groups. You will get more information, and better information, in a series of short chats with a few people than in marathon meetings of many people. Meet only to resolve conflicts or build consensus.
Capturing the Critical Information
The author suggests a number of basic questions to ask in order to capture the most critical information:
What Are the Business Purposes of the System?
A clearly defined business purpose helps team members to focus on the goal, rather than details that may be irrelevant. It can serve as a touchstone for determining what features are really necessary. It can serve as a standard to rally the team to a common goal (and avoid conflicts and misunderstandings).
A given project may serve multiple purposes - in which case, it is important to list and prioritize them, as well as ensuring that there are no conflicts among the purposes.
It's also worthwhile for the purposes to disclose the practical impact of achieving the stated purposes. It doesn't need to be detailed and formal, but the value of the project is not self-evident. EG: "to improve logistics" is not as compelling as "to increase customer satisfaction by decreasing the amount of time it takes to deliver their orders" or "to decrease expenses by eliminating redundant labor in the shipping department"
What Are the Main Elements of the System?
Brainstorming should be done to come up with an extensive list of the elements (people, systems, data, reports, etc.) that are involved or impacted by the proposed system. Again, it is easier to begin with a too-long list and eliminate those that are not affected than to try to discover items that may be missing from a too-short list.
What Should the System Do?
This should describe the basic actions of the system in layman's terms and provides a high-level overview of the functions. It would be sufficient to document that it "analyzes transactions for unusual activity and reports them" without the granular details about the databases it will act upon, the algorithm that will be used, or the recipients of the report.
How Are These Tasks Currently Being Handled?
In most instances, a project will replace an existing system that is currently doing the same task with an eye toward improvement. It's important to document existing functionality with an eye toward preserving it.
- Ask what the system does, and get an objective assessment of the tasks it performs.
- Ask which of these tasks are necessary to continue to do going forward.
- Ask what the system does well, so you can ensure that the same performance standards are met by the replacement
- Ask what the system is doing poorly, which will identify areas for improvement.
- Ask what external data the current system relies upon. They may be data sources for the new system, or if it is discovered the new system doesn't need them, it may identify unnecessary components that can be phased out.
- Ask what systems and individuals receive information from the current system, to ensure that the new system feeds them as well.
What Do We Hope the New System Will Do Better
Aside of overcoming the present system's faults, make a separate inquiry as to what might be done better to gain insights on improvements.
Writing the Outline
Outlining is a method of developing the framework as a document so that you can assess whether it will (eventually) contain all the needed information, and it provides structure to the task of developing the content.
What to Include, What to Leave Out
The author rails, for a bit, against project management doctrines that prescribe letting the developers "wing it" without documentation to guide them. It sounds like a bad idea at face value, but it's exactly what some PM theories advocate. He supposes this to be a reaction to bad documentation - too specific, too vague, lengthy, incomprehensible, and expensive to produce - but getting rid of it altogether is not a sage practice.
Documentation need not be lengthy or complex - for a simple project in a fast-moving environment, it can be a few pages that provide a bare-bones description - though the larger, more complex, and more expensive a project, the greater the need for documentation to avoid ambiguity and wasted effort.
During the outlining stage, the discussion should include the required level of detail, and a consensus should be achieved to determine what does, or does not, require documentation.
A Generic Outline
As a basic outline, the author suggests:
- Executive Summary - Summarizes the project, generally with a perspective of the benefits that will be provided and the costs that will be undertaken.
- Current State - A description of the systems and functions that are currently in place
- Future State - An explanation of the system that will be built
- Gap Analysis - A comparison of 2 and 3, with an eye toward what the project proposes to change
- Requirements Summary - A list of the business requirements
- Appendices - Any reference material necessary to other parts of the document
An Agile Outline
"Agile" is a project management methodology that's currently in favor, whose methodology generally consists of breaking up a large project into smaller pieces that can be more rapidly accomplished. Agile project descriptions follow a template:
- Summary - Discloses the business purpose and success criteria
- Nonfunctional Requirements - The benefits of the project as perceived by the business
- Future State - Same as above (present state is skipped)
- Data Requirements - Documentation of the inputs the system will require
A Robust Outline
Larger organizations, with larger projects, generally have a need for more detailed documentation with nuts-and-bolts details. This can get monstrous, and the author suggests the following approach:
- Executive Summary - Including a problem statement, recommendation, key requirements and success criteria, and scope statement
- Gap Analysis - A description of the current system, proposed future state, and differences
- Requirements summary - Including functional, nonfunctional, business rules, and delivery requirements
- Appendices - Data descriptions, report descriptions, and UI illustrations