Introduction
As the subtitle of my blog suggests, I like to share in here some of my key Power Platform and D365 recipes with you. Today, I’m tackling a topic that many people tend not to like, yet it is crucial for any project – documentation.
In the world of Power Platform and Dynamics 365 (D365) projects, the importance of creating thorough and well-structured functional specification documents (FSDs) is vital.
An FSD serves as a blueprint that guides the development, ensures alignment among stakeholders, and sets the foundation for testing and deployment.
My recipe on FSD aims to explore the essential components of an effective FSD, explain their significance, and provide some examples from Power Platform and D365 projects.
Over the years, I’ve learned that everyone has a slightly different approach of creating an FSD and the templates used across different companies also vary. Additionally, each project is unique, so it might require some additional sections. And in the contrary - some of the sections I cover here might not be needed as the solution does not contain specific components.
Treat the blog as a guidance and help, but always ensure you cover all the basics that are specific to your projects and solution design.
FSD Components
A comprehensive FSD typically includes sections on project scope, functional requirements, process flows, data models, user interface designs, security and access controls and integration points (with details being covered in an integration spec doc or TDD – technical design doc).
Let’s dive into the details of these components.
Title page
Title page should include the following:
· Project Name/Customer,
· Document Title (i.e. Functional Specification Document),
· Version Number,
· Date,
· Author(s).
Table of Contents
Next, include a table of contents that list the sections with page numbers. You can also include a list/table with all the figures and tables in the document with page numbers.
Document Control
Document versioning or document control contain details of all the versions of the document and details what changes have been made to each version. Usually I start with a version 0.1 as an initial draft of a document and once a document is ready to be published is marked as a version 1.0.
Glossary
Although functional spec docs are usually written in plain language, it is still very helpful to include a glossary that explains key terms like Dataverse, table (entity), model-driven app, etc.
Overview (or Executive Summary)
The executive summary section is almost like an appetiser of the FDD, providing brief overview of the project, the purpose of the document and high-level goals and objectives.
Alternatively, you can start with an overview section. Here, provide customer background, a high-level overview of the project, outline the purpose, objectives/goals, and key deliverables. This sets the stage for the detailed sections that follow.
This section provides context for the Power Platform solution, explaining why the project was initiated and the conditions that led to its inception. This section helps stakeholders understand the historical and situational context that necessitated the project.
Examples:
Customer background: AMB Consulting is looking for a new CRM system to support their processes of managing sales and customer relationships.
Project purpose: The purpose of this project is to develop a custom CRM solution using Dynamics 365 to streamline the sales process, improve customer engagement, and enhance reporting capabilities.
Document Scope
List what key business processes are being covered in the document and what are the solution components details, e.g. tables, automation, customisation.
Examples:
This document evaluates a set of.....
It explains the key features and benefits of this solution in line with the requirements.....
The document contains an analysis.....
This document also details how the business requirements are delivered with the Power Platform components / Dynamics 365 features and functionality.
This FSD covers the data maintenance approach and security model.
Processes Overview
Include overview of the key business processes. Ideally, include high level process maps and briefly explain the key steps of each process.
Business Requirements
The FSD is not a BRD (Business Requirements Document), so it does not contain the full details of the requirements. However, still include a list of all the business requirements, including titles and references. Also, provide the details of the document that contain the business requirements with their location to e.g. SharePoint or Azure DevOps.
Functional Overview
This section includes details of the solution functionality. One approach is to drive this by the processes explained in the “Processes Overview” section or by the business requirements. Regardless of the approach, provide a functional description of how the application will work and how the users will engage with it.
Describe the functional design, its purpose and the intended functionality. That can consist of:
Step-by-step description of the process supported by the development,
Diagram of each step of the process and how they relate to each other,
Summary of what the outcome of the process is.
Solution Overview
In this section, provide high level overview of what components solution will contain and their purpose. For example, all the model-driven apps, canvas apps, portal, azure functions.
Solution Architecture
If you are implementing a mix of different apps and native integrations, include a section with a solution architecture. In this section, include a diagram showing the different components and if there is any integration between them and if there are using the same database.
Explain the details of each integration and their purpose. For the native integration, a functional description is sufficient. For any custom integration, a separate document needs to be created.
Entity Relationship Diagram (ERD)
The next key diagram in the FSD is the entity relationship diagram showing the relationships between the tables used in the solution. If you are implementing a complex solution with large number of custom tables, only show the key ones to make sure your ERD is readable.
In this section, you can also include a table with all the tables and provide a brief description of the purpose of each of the tables (entities).
Once the solution is built, you can also include an attachment with all the metadata for each of the tables. Use XrmToolBox tool – Metadata Document Generator.
Solution Design Details
This section contains details of how the functionality described in the previous section will be built.
The solution design outlines the detailed architecture, components, and processes of the Power Platform solution. This section provides a comprehensive blueprint for how the solution will be implemented, ensuring all technical and functional aspects are covered.
If your solution contains a model-driven app, you might want to include:
OOTB and custom tables,
Forms,
Table relationships,
Field requirements,
Business rules,
Business Process Flows,
Views,
Automation (classic workflows/Power Automate flows).
For the canvas app include components and their description for:
OOTB and custom tables,
Screens with their details – name, fields, buttons, etc.,
Galleries with views,
Automation, etc.
If some of the requirements need a custom logic that requires e.g. plugin, I would reference it in here. However, I would request a technical consultant or a developer to create a TDD (technical design document).
User Interface Design
This section should include details of the User Interface design and contain:
Wireframes and mock-ups,
Description of each screen,
Navigation flow.
Security
In the security sections, cover details of the security roles and what privileges users and teams will have. Include security model, user authentication and role-based access control.
Security Model
In this section, define the overall security framework for the Power Platform solution.
Outline the security principles and policies that the solution will adhere to (e.g., least privilege, role-based access control). Make sure you have considered any licensing implications of your security model.
User Authentication
In here, specify the authentication methods supported (e.g., Azure AD, multi-factor authentication) and include the process for user login and session management.
Role-Based Access Control
Additionally, define how to control access to resources based on user roles. Also:
List the roles that will be used within the Power Platform solution (e.g., Admin, Power User, Read-Only User).
Provide a matrix mapping roles to permissions and access levels for different components (e.g., Power Apps entities, Power Automate flows).
Outline any custom roles that need to be created and the specific permissions they entail.
Data Maintenance
Data Maintenance is another very key aspect of any FSD. If you have specific requirements around maintaining data quality, data clean up or retention policies, include a Data Maintenance section. In here, detail duplicate detection rules, bulk edit and any other automation that will be needed to meet the requirements.
Word Template FSD
Are you looking for an FSD Word Template?
Head to my LinkedIn post and leave a comment under it and I will send you a copy! (Alternatively, send me a DM via LinkedIn).
The template contains a glossary, all the sections as in my article, more real-life project examples from FSDs, tables and so more info that I did not cover in here!
Conclusion
Writing very long documents is not necessarily a fun activity, is it? Luckily, more and more projects are delivered in more of an AGILE methodology rather than waterfall. While the waterfall require for the FSD to be created before any development start, with the AGILE projects, the FSD are more a “living document”. That makes the documentation less challenging. On most of the occasions you can document the solutions in parallel of building them.
However, no matter what approach you are taking, it is always a good practice to create comprehensive design documents. Why? There are many reasons for that, so I will only give you a few. First of all, these documents contain the details of the solution build and help to drive the proper testing of the solution. Secondly, they can be used as the basis for creating training materials.
Additionally, post go-live they help with any troubleshooting and issue resolution. They are also used to understand the basis of the solution and how the solution can be extended by implementing further enhancements in the future.
Use my article as a guide and inspiration, but always approach any project documentation with the aim for it to cover the basics of your solution rather than keeping to rigid to any templates.
Remember, a well-crafted FDD lays the foundation for a successful implementation and has long-term value to the customer.
Good luck!
Kommentare