Community Projekt zur automatischen Dokumentation von Power Apps

Microsoft Power Apps ist eine „Low code“ Applikationsplattform, mit der „nicht Programmierer:in“ (Endanwender:in, Personen aus dem Business) in die Lage versetzt werden sollen, schnell eigene Applikationen für Mobile Anwendungen oder das Web zu erstellen. Dabei werden vorgegebene Komponenten (Buttons, Eingabefelder, Listen, Gallerien, etc.) nach dem Baukastenprinzip zusammengestellt, welche dann die UI, also die graphische Benutzeroberfläche bilden. Die Logik, also die Funktionen werden zu jeder Komponente in einer Funktionssprache (ähnlich der Excel Funktionen) angegeben.
Mithilfe von Power Apps lassen sich somit nicht nur schnelle Lösungen für kleinere Anwendungsfälle realisieren, sondern es können auch komplizierte, den Arbeitsprozess unterstützende  oder abbildende Applikationen entwickelt werden, die von einer Vielzahl an Mitarbeitern täglich genutzt werden.
Werden solche Applikationen allerdings Businesskritisch, sollten auch die Anforderungen an Zuverlässigkeit, Wartbarkeit sowie Dokumentation steigen. Eine Dokumentation wird in der Praxis von „nicht Programmierern“ aus Unkenntnis oder weil dem Thema keine Dringlichkeit bzw. Notwendigkeit beigemessen wird, nicht gemacht. 

Die Dokumentation von Microsoft PowerApps ist ein wichtiger Baustein im Softwarelebenszyklus. Wie bei klassischen Softwareprojekten sollten auch die in PowerApps entwickelten Lösungen Dokumentiert werden, um Weiterentwicklung, Support und Wartung sowie das Onboarden neuer Entwickler gewährleisten zu können.
Aktuell ist es allerdings nicht „out of the box“ möglich eine Dokumentation für eine Power App weitestgehend automatisch zu erstellen. Darüber hinaus gibt es seitens Microsoft auch keine klaren Empfehlungen was in solch einer Lösung dokumentiert werden sollte.

PowerApps-Docstring

PowerApps-Docstring ist eine Applikation, welche, basieren auf dem Power Apps Code, automatisiert eine Dokumentation der App erstellt. Grundlage hierfür bilden die in den Funktionsbausteinen eingegebenen Docstrings sowie die genutzten Bausteine und Screens. Zurzeit besteht die Dokumentation aus folgenden Bereichen:

• App Beschreibung (aus Docstring in App.OnStart)
• Verbindungen
• Screenflow (Bildschirm-Fluss Diagramm)
• Bildschirmbeschreibung (aus Docstring in OnVisible)
• Inhalte des Bildschrims inkl. Funktionen (Konfigurierbar)

Welche Anforderungen mussen erfüllt sein, damit die Dokumentation automatisch erstellt werden kann?

Die Dokumentation einer Power App wird aus den einzelnen Quelldateien, welche im Source-Ordner enthalten sind, automatisch extrahiert. Welche Informationen zur Dokumentation hinzugefügt werden sollen, kann in der config.yaml Datei festgelegt werden. 

Beschreibende Texte und Erläuterungen zu einzelnen Screens, Objekten oder Propperties können jeweils am Anfang vor die eigentliche Funktion mit /* Text */ vorangestellt werden. Diese werden dann an die entsprechende Stelle der Dokumentation übernommen.

Ein in der App erstellter Docstring wird für jedes Element und Propperty aus der config.yaml in die Dokumentation übernommen.

Pipeline basiertes und lokales Erstellen der Dokumentation

Zurzeit ist PowerApps-Docstring eine Python Applikation welche mit der Kommandozeile aufgerufen werden kann. Dies bietet die Möglichkeit das Erstellen der Dokumentation in eine CI/CD-Pipeline in Azure DevOps zu integrieren, wo die Dokumentation dann automatisch für Änderungen an der Power App erstellt wird. 

Die Python Applikation kann ebenso auf einem lokalen Rechner ausgeführt werden. Eine Anleitung hierzu findet sich ebenfalls in der Repository. Dabei wird auf Grundlage des Quellordners (/src) und der darain enthaltenen .yaml Dateien die Dokomentation aus den Docstrings und dem Code extrahiert und als Markdown Datei zur Verfügung gestellt. 

In einer späteren Version soll es auch möglich sein die Dokumentation aus der .msapp oder .zip Datei zu extrahieren.  

Guideline für das Anfertigen von Power Apps Dokumentationen

Neben der Erstellung einer Dokumentation stellt das Open-Source Projekt ebenfalls eine Guideline bereit, welche die Mindestanforderungen an eine Softwaredokumentation bezogen auf Power Apps beschreibt. Diese soll dem:r in der Softwareentwicklung unerfahrenen low code Entwickler:in die wichtigsten zu dokumentierenden Themen nennen sowie als Beispiel für eine gute Dokumentation dienen.

 

Community Projekt

PowerApps-Docstring ist ein Community Projekt ins Leben gerufen von der #CloudCouchRocks #PowerAtelier Community von Stefan Riedel und Tomislav Karafilov.

Fehler, Feedback oder Ideen können direkt als Issue in der Github Repository aufgemacht werden.