Project Documentation - A Primer

Summary

• Requirements Document, which covers a lot of the territory of the project.
• Technical Specification focuses on the how of a technical project
• Sitting between the business and tech team is the Functional Specification
• We'll then run through some data focussed documents

It's time to close Power BI Desktop, shut down your IDEs, and put away your Jupyter Notebooks because this one is about documentation. And upon writing that, I realised how boring that sounds but trust me; it'll help, so let's get to it.

‍Requirements Document

A requirements document is simply a guide that tells everyone involved in a project what is needed and expected from the developed product or system. Think of it as a list of everything the product should do to deem the project successful.

This document helps keep everyone on the same page about what the product should do before the work of building it begins. It's like a roadmap that helps keep the project on track.

Requirements Docs usually include headings like:

1. Purpose: As in, why are we even going to do this project
2. Users and Stakeholders: Who will use/benefit from the new solution and the stakeholders surrounding them?
3. Functional Requirements: A concise list of the things the product should do. For example, a functional requirement of a Power BI deployment might be "users should be able to search for sales figures by territory, by month, by agent".
4. Non-Functional Requirements: These are the qualities the product should have. For example, the report might need to be fast, easy for entry-level staff, or optimised for different devices.
5. Constraints and Assumptions: These are any limits or conditions that must be considered during development. For example, the report might need to use specific data sources or be developed in a certain timeframe.
6. Success Criteria: This is how you will know when a requirement has been met. For example, "the report loads in under 2 seconds".

Technical Specification

Think of technical specs like a blueprint for building a house. They're intricate, highly detailed, and should leave readers with absolutely no questions about how to build the thing.

When considering a data project, a technical spec should include the following (with building a house analogy to boot):

1. Data Architecture and Design: This is the foundation and layout of your building. It details how your data will be structured, organised, and stored and how different data sets will interact.
2. Technologies and Tools: These are the building materials and tools you will use. For a Power BI project, this would include the specific data sources, the software or cloud environment where Power BI is deployed, and any other technologies that will be used.
3. Data Processing Procedures: This is like the plumbing and electrical systems. These procedures outline how data will flow through the system, including how it will be cleaned, transformed, and analysed.
4. Dashboard and Report Design: These are the floorplan and interior designs of your building. They determine how your users will interact with the data. This includes the layout and design of your Power BI dashboards and reports, the visualisations you will use, and how users can interact with them to gain insights.
5. Security Measures: These are the locks and alarm systems for your building. They ensure that only authorised users can access your data and that it's protected from threats.
6. Performance Parameters: These are like the environmental conditions your building must withstand (like wind, rain, temperature, etc.). For a Power BI project, this could include the speed of data refresh, the responsiveness of your dashboards, etc.
7. Deployment Plan: This is your construction timeline. It outlines how the Power BI solution will be rolled out to users, including any necessary preparations and steps to take after deployment to ensure everything is working as expected.
8. Testing Plan: These are your building inspections. They ensure that everything in your Power BI deployment is working as it should and meets all the requirements you laid out at the beginning of the project.

As mentioned, an excellent technical spec leaves no guesswork. If there is room for interpretation, your tech writer hasn't done their job.

Functional Specification

Similar to the requirements doc and in contrast to the technical spec, a functional spec (FS) focuses on what a particular part of the project should achieve. If a requirements doc covers "we need to improve our overall analytical capabilities" and functional spec covers "here's what a specific report should do".

If we continue the building analogy (and please note, I am NO builder), it's like describing the type of house you want without detailing the materials to be used or how it should be constructed.

Here's what a functional specification for a Power BI deployment might include:

1. Introduction: This is where you provide an overview of the project. In our context, you'd explain that you plan to implement Power BI as a solution for data visualisation and analysis. It's like setting the stage before the play begins, giving a broad idea of what's to come.
2. Scope: The scope is where you outline what the Power BI project will cover and, equally important, what it will not cover. Think of it as defining the boundaries of your project 'property'. This could include which areas of the business it will impact, which data sources it will use, and what kind of analyses it should be able to perform.
3. As-is Process: This section describes the current state of things before the Power BI deployment. It's like taking a snapshot of your existing data management and reporting methods. Understanding this can help highlight the problems and inefficiencies that Power BI is supposed to solve.
4. Business Outcomes: Here, you describe the desired outcomes or benefits for the business after Power BI is deployed. It's the 'why' behind the project. This could include improved data visualisation, better decision-making, time savings, etc. These are the positive changes you expect to see once your project is implemented.
5. To-be Process: This is where you describe what the new process will look like with Power BI in place. Imagine drawing a picture of how data will be handled, reported, and analysed after the project is complete. This gives everyone a clear vision of what to aim for during the project.
6. Change Management: In this section, you outline the process of transitioning from the current 'as-is' state to the desired 'to-be' state. For a Power BI project, this could involve training for staff, dealing with resistance to change, ensuring data integrity during the transition, etc. It's like planning a road trip from your current location to your destination, including the route, stops along the way, and how you'll handle any potential roadblocks.

This functional spec sets the expectations for your Power BI deployment. It provides a clear understanding of what the final product should do, who it is for, and how its success will be measured. The technical spec would then use this as a base to detail how to achieve these functionalities.

Data Focussed Documents (which deserve their own posts)

1. Data Dictionary: A catalogue or a detailed description of all the data elements relevant to the project. It includes information about each data element's meaning, relationships, origin, usage, and format. Just as it sounds - a dictionary for data.
2. Data Model: This document describes how the data is structured and organised. It may include entity-relationship diagrams or other types of schema diagrams.
3. Data Flow Diagram: This shows how data moves through the system, including inputs, processes, and outputs.
4. Data Preparation/Wrangling Documentation: A record of all the data cleaning and preparation processes, including dealing with missing values, outliers, and transformations applied to the data.
5. Model Development Documentation: This includes the methodologies used, hypotheses tested, variables used, model selection and validation, etc.

Not an exhaustive list, and each could get its own post. But a primer on what to expect when you first enter the project world.

You can see how your technical skills need to meld with your other skills like writing, communication, and stakeholder management. These documents go through many hands, have many contributors, and require multiple sign-offs.

There are many I haven't covered, but this should get you on the way to understanding the paperwork involved in the beautiful world of projects.