Different Project Documents

I have found that often there is a lot of confusion around the different artifacts –the different documents– that might be needed for a project, or in a particular software or technology-driven shop. Much of the confusion is in the naming convention of these documents (docs), and in the fine line delineation between them all.

Different Documents
So, I have decided to put all I have learned, coupled with a few plagiarized searches, into this one post –A repository describing the most common documents involved in a typical Software Development Life Cycle (SDLC).

But before I jump right into it all, I ask that you share with us all your feedback ... feedback on the post itself and on any other artifacts that might require clarification.

Technical Requirements Doc. (TRD) –It includes the layout of the systems, firewalls, performance, SLA’s, and general & specific details of the technical implementation process (this includes the environments, along with sessions, load-balancing, data mappings, etc.).

A different document, but is a sub-set of the TRD, is the Entity Relationship Diagram (ERD). This should include the [logical] data model (LDM), which’s different* from the ERD but quite similar.

Data Dictionary –Tables, columns, data types and descriptions.

* A logical model is slightly more abstract than a physical model. A physical model represents exactly what is implemented in a database ... table and column names are as they exist in the schema, you define indexes, specify column datatypes and sizes, contraints, tablespaces, partitions and all the other requirements to actually define the database. A logical model shows entities, attributes, keys and relationships. Names are usually more free-form and descriptive. Often, "conceptual models" sometimes get confused with "Logical Models".

A conceptual model might have a fact table with the dimension tables but without any column names. Some of the dimensions might later be split into 2 or combined. It's almost a graphic presentation of the BUS Architecture.

The logical model might have the column names in lay terms - "Group Identifier" instead of group_id. There may not be difference between a view and a table.

And the Physical Model is what the database physically looks like.

To many, there is no logical dimensional model. Conceptual and logical models are normalized data structures used to define data dependencies. Unfortunately, there is no consensus on what goes into a conceptual model other than it is less than the logical data model.

In layman’s terms …
A Conceptual Model is what you do on a scrap piece of paper.
A Logical Model is what you do in Excel.
And the Physical Model is what you get when you use Visio to reverse engineer the database.
Actually, a variation on the conceptual model comes in handy when setting up the reporting tools.

Business Requirements Document (BRD) –This is your project scope. It’s the reason behind the madness. Why the project is needed, and how the vision of the project is supposed to come into manifestation. This also includes the commitment to the delivery of the project. The BRD can be an extension of the SOW. The BRD should include the process required/needed, which represents the project along with any process-flow and logical diagrams. Functionality is not part of the BRD. The BRD acts a summary of the detail that would ultimately make it into other documents, like the Functional Specs. Document (FSD).

Functional Specifications Document (FSD) –This document includes logic and details to implement the business vision, process and overall project in technical terms. The FSD includes object definitions, and may include procedure definitions as well. The FSD includes use cases, which later make it into Quality Assurance’s (QA’s) Test Plans. The FSD is divided or represented into different functional areas that relates to the different working parts that make up the overall project. Examples includes, data feeds, reports, campaigns, business intelligence deliverables, etc. These areas are represented in the BRD at a high-level and include the functionality aspect here. As such, and in most cases, some of these are divided into their own respective documents; which are still a sub-set of the FSD.

  Campaign Requirements Document (CRD) –This could address the overall architecture, process, inputs/outputs and overall handoffs of a campaign, as well as a listing of each campaign expected. The result should be a document, which houses all the campaigns agreed upon as part of this project’s scope & deliverables. Upon completion, this document is handed over to Production Support.

  Business Intelligence Requirements Document (BIRD) –This document, on its own, should provide enough specificity with respect to the kinds of business intelligence applications that are needed; including the different kinds of applications, from basic reporting and OLAP to sophisticated analytics. In general, this document guides development of the business intelligence databases and applications that deliver the BI, or to guide the business process changes that deliver the bang for the buck to the business.

Warning: I'm about to digress for a little bit ...

The BIRD is more than the following traditional statements:
  • “…produce enhanced organizational capabilities to manage data and information as organizational assets.”
  • “…provide a single version of the truth.”
  • “…enable consistent and reliable access to accurate corporate-wide data.”
  • “…provide more sophisticated reporting and analysis, faster turnaround, improved accessibility and enhanced quality.”
  • “…a single touch point where detailed financial transaction information can be filtered on user-entered selection criteria, viewed online, downloaded in standard file formats and used to generate real time reports.”
And it’s also more than the traditional BI Functional Specifications:
  • The system shall provide the ability to drill down, drill across, and slice-and-dice.
  • The system shall provide the ability to specify organizational hierarchies and display performance scorecards for each organizational unit.
  • The system shall enable role-based access to information.
  • The system shall provide capabilities to route alerts to business users according to user-defined parameters.
  • The system shall enable integration of data from multiple disparate sources.
And most of all, it’s more than the traditional Give Us Everything We Might Need and We’ll Figure Out What to Do with It.

While such data element listings can be helpful, and while we need to understand what business information is needed as a core expression of BI business requirements, the listing alone says nothing about how the information will be used or how it might need to be integrated with information about products, manufacturing locations, store locations, organizational units and other organizational information. Further, BI capabilities built on top of large stores of unintegrated subject data elements run the risk of spawning inconsistent business intelligence depending on how development teams and/or power users choose to integrate data for their specific purposes. In other words, simple data element listings don’t provide enough specificity to guide development of the BI databases and applications that deliver business intelligence or to guide the business process changes that deliver the bang for the buck to the business.

Instead, the BIRD should be Business-Driven BI Requirements

A. Establishes a clear linkage between business strategies, the core business processes via which the strategies are executed, and BI-driven business improvement opportunities, which is the basis for a BI business case that is compelling to the business stakeholders;
B. Identifies and clearly describes what business information, analytical tools and techniques, and decision support is required by the business to realize BI-driven improvement opportunities to management processes, customer processes and/or operational processes;
C. Provides the essential input to the process of defining specific BI projects and prioritizing those projects based on key criteria such as business impact and time-to-market;
D. Provides the means of aligning business intelligence, business process improvement and balanced scorecard initiatives;
E. Drives key data architecture decisions;
F. Provides the basis for end-to-end traceability between BI requirements approved by business users and the delivered data stores and BI applications; and
G. Provides a key baseline against which the performance of the BI initiative can be measured.

Data File Layout (DFL) –Description of data fields. Note how this works in tandem with the ERD, data model and data mappings; which are typically part of the TRD, or a sub-set of that.