Power Platform Solution Documentation Tips

Documenting Power Platform solutions is a critical part of the development process - even if it is not always the developer’s favourite task. However, it is essential to have good documentation that helps to understand the solution architecture, the solutions themselves, their components and the data flows between them. The documentation should be understandable to developers, administrators and other stakeholders.

Documenting Power Platform solutions

Let’s start with the high level overview of the solution, showing the main functional components and their interactions / relationships. Zooming in, we can then describe the functional components in more detail, showing their inner structure and data flows.

The deployment architecture shows the deployment of the solution, mostly including the relevant infrastructure components and their relations. The design decisions view shows the most important design decisions that have been made during the design phase.

High Level Overview

A very good starting point here is the context diagram, showing the solution as a “blackbox” and its environment (such as other systems and users). The components are then described in more detail, showing their inner structure and data flows.

The refinements could be done in several steps, starting with the context diagram and then adding more details:

1. context diagram (can be taken from requirements specification); an overview of the solution / app (as a “blackbox” – without looking into the details), showing it in the relation to the environment (such as other systems and users) and the exchanged data between the nodes (an according arrow pointing to the appropriate direction)
2. Whitebox diagram of the complete solution (“Whole system”); contains all Power Platform solutions as well as other services / components and their data interactions (in a list or table: service name / API and data flows / description of purpose)
   👉 no need to show all details, no need to describe all services in details (“blackbox” view)
3. (optional) Functional Components (Power Platform solutions): zooms in every Power Platform solution and contains for example selected services and their inner structure (such as service components); examples:
   • The Power Automate flows and their connections to M365 services or external data sources
   • The Canvas app and its screens and the interactions between them, the components and their data sources
   • The “modules” of the model driven app, their data sources (without showing tables and fields) and relations between them
   • API layer: API Management and a selection of certain API functions

Deployment architecture

The deployment view shows the deployment architecture of the solution, mostly including the relevant infrastructure components and their relations. It should only show the solutions’ main components and their deployment to the specific environment(s). In case of multiple environments, the deployment view should show the deployment paths from one environment to another.

Design decisions

The design decisions view shows the most important design decisions that have been made during the design phase. It should always point to the according decision(s) by explaining WHY and HOW a specific technology or the decision to use certain (external) components were taken into consideration. Make use of a simple table that lists the decisions and their rationales.

You can also use a simple list of decisions, but a table is more structured and easier to read. Consider the following link for a easy to use template: Architectural Decision Records; look for the «Markdown Architectural Decision Records (MADR)» section that contains a full or minimal template.

Documenting Power Apps

Describe all (functional) components of the Power Apps solution and how it is structured. Key aspects to consider:

• Screens and Descriptions: the screens that are accessible (to the users or user groups) and the interactions between them (navigation paths)
• Data sources and connectors: the main data sources and their connectors (as well as the data flows; unidirectional or bidirectional)
• Workflows: the main (Power Automate) workflows and their triggers (and the data [objects] they are working with); no need to describe the workflows in detail!
• Third Party Components: additional components that are used in the app and a short description of their purpose

Documenting Power Automate Flows

When it comes to documenting Power Automate workflows, it is important to provide a high-level overview of the workflow that makes the need to look into the existing implementation of the workflow obsolete. The documentation should be understandable to developers, administrators and other stakeholders.

Therefore, try to describe the workflows and their inner structure. Key aspects to consider:

• General description: description of workflows from a high-level perspective (purpose)
• Trigger: the trigger of the workflow (e.g. “When a new item is created”) and the trigger conditions
• Permissions: permissions and any data connections that make use of the according permission
• Basic workflow sequence: sequence of the workflow (in a table: step / action / description) that shows the main steps of the workflow (avoid too much detail)

Example

Following example shows a simple documentation of a Power Automate workflow along the lines of the above mentioned aspects. The workflow data was taken from an example workflow, and the description was generated by using Github Copilot.