Eine M365-Anleitung schreiben, die andere wirklich nachbauen können.
Voraussetzungen, Schritte mit erwartetem Ergebnis, Wirkung auf den Tenant und Aufräumen. Zwölf Punkte und eine Gliederung für Anleitungen, die tragen.
Du kennst diese Anleitungen. Schritt 3 verweist auf ein Menü, das es nicht mehr gibt. Das Skript bricht mit einem Fehler ab, der nirgends erwähnt wird. Und ob das Ergebnis stimmt, weißt du nicht, weil nirgends steht, wie es aussehen soll.
Ich schreibe selbst Anleitungen. Und meine älteren sehen teilweise genau so aus.
Eine Anleitung ist ein Versprechen an jemanden, den du nie triffst. Sie hält, wenn diese Person ans Ziel kommt, ohne dir schreiben zu müssen.
Was nachbaubar heißt
Eine Anleitung ist nachbaubar, wenn eine fachkundige Person ohne Rückfrage zum selben Ergebnis kommt und erkennt, dass sie angekommen ist. Der zweite Halbsatz ist der, den die meisten vergessen.
Dafür braucht es drei Dinge. Voraussetzungen, die vor Schritt 1 stehen. Schritte, die sagen, was zu tun ist und woran man sieht, dass es geklappt hat. Und Grenzen, also was die Anleitung nicht abdeckt und wo sie scheitert.
Dazu ein Datum, zu dem alles gestimmt hat. Microsoft 365 ändert sich jede Woche. Eine Anleitung ohne Datum ist eine Wette.
Zwölf Punkte, an denen ich jede Anleitung messe
Rahmen
- Ziel und Nicht-Ziel. Ein Satz, was am Ende vorliegt. Ein Satz, was die Anleitung nicht leistet.
- Stand. Datum, zu dem die Schritte gestimmt haben. Bei Skripten zusätzlich, ob sie in einem Tenant gelaufen sind.
- Zielgruppe. Für wen, mit welchen Vorkenntnissen.
Voraussetzungen
- Rolle und Berechtigung. Die geringste, die reicht, mit Begründung.
- Werkzeuge. Module, PowerShell-Version, Lizenzen.
- Eingaben. Welche Werte du brauchst und wo du sie findest.
Schritte
- Lückenlos. Kein Schritt setzt etwas voraus, das vorher nicht genannt wurde.
- Erwartetes Ergebnis. Mindestens am Ende steht, wie die richtige Ausgabe aussieht.
- Wirkung. Liest oder ändert die Anleitung? Was bleibt im Tenant zurück?
Grenzen
- Einschränkungen. Was nicht erfasst wird, wo Mengen- oder Typgrenzen liegen.
- Fehlerfälle. Die zwei, drei häufigsten Fehler und was sie bedeuten.
- Sicherheit und Aufräumen. Umgang mit Secrets, mit personenbezogenen Ausgaben und mit dem Rückbau.
Die Wirkung und das Aufräumen fehlen in fast jeder Anleitung. In Microsoft 365 sind sie die wichtigsten Punkte. Eine App-Registrierung mit Leserechten auf alle Gruppen, die nach dem Test einfach stehen bleibt, ist eine dauerhafte Änderung am Tenant. Auch wenn das Skript „nur liest“.
Mein eigener Planner-Beitrag als Beispiel
Im Oktober 2024 habe ich PowerShell - Teams Planner Task Report veröffentlicht. Ein Skript, das über Microsoft Graph die Aufgaben aller Pläne einer Teams-Gruppe in eine CSV schreibt. Es tut, was es verspricht. Für jemanden, der weiß, was er tut.
Ziel, Eingaben und Reihenfolge stehen drin. Was fehlt, sind die Geländer für alle anderen.
- Die Wirkung. Das Skript liest. Die Vorbereitung legt aber eine App mit mandantenweiten Leserechten und einem Secret an. Das gehört in einen eigenen Absatz.
- Das Aufräumen. Das Secret steht im Klartext im Skript. Heute käme ein Abschnitt dazu mit kurzer Laufzeit, sicherer Ablage und dem Entfernen der App nach Gebrauch.
- Die Daten. Die CSV enthält Namen und Aufgabentitel. Wo sie liegt und wann sie gelöscht wird, gehört geregelt.
- Das Ziel. Dateiname und Spalte „ClosedBy“ klingen nach abgeschlossenen Aufgaben, das Skript filtert aber nicht. Ein Satz würde das klären.
- Das erwartete Ergebnis. Eine kurze Beispielausgabe mit erfundenen Daten, damit man sieht, wie ein vollständiger Bericht aussieht.
Bei den Berechtigungen bin ich inzwischen weiter. Für Pläne und Aufgaben reicht Tasks.Read.All. Was das für das Skript bedeutet und wann du den App-Weg überhaupt brauchst, steht in Planner-Berichte mit PowerShell. Aus Aufgaben werden Entscheidungen.
Die Gliederung für eine neue Anleitung
Wer neu anfängt, spart sich die Nacharbeit. Ich baue jede technische Seite so auf.
| Abschnitt | Inhalt |
|---|---|
| Kopf | Titel, Stand, im Tenant gelaufen ja oder nein |
| Wozu | Ziel und Nicht-Ziel in zwei Sätzen |
| Für wen | Zielgruppe, Vorkenntnisse |
| Was du brauchst | Rolle, Berechtigungen, Werkzeuge, Lizenzen, Eingaben mit Fundort |
| Was dabei passiert | Liest oder ändert, was zurückbleibt |
| Schritte | Nummeriert, je Schritt Aktion und erwartetes Ergebnis |
| Ergebnis kontrollieren | Wie die richtige Ausgabe aussieht, woran du Lücken erkennst |
| Wenn etwas schiefgeht | Häufige Fehler und ihre Bedeutung |
| Aufräumen | Rückbau, Ausgabedateien, Secrets |
Für einen einfachen Handgriff ist das zu viel. Dann reichen Stand, Voraussetzungen und erwartetes Ergebnis. Sobald aber eine App-Registrierung, ein Secret oder eine Änderung am Tenant im Spiel ist, gehört die volle Gliederung dazu.
Und ein ehrliches „im Tenant gelaufen, nein“ im Kopf ist mehr wert als ein unausgesprochenes „wird schon stimmen“.
Die Gegenprobe kostet zehn Minuten
Bevor eine Anleitung online geht oder ins Handbuch wandert, gib sie jemandem, der sie nicht geschrieben hat. Nicht zum Ausführen, nur zum Lesen. Die Aufgabe ist einfach. Jede Stelle markieren, an der man nachfragen müsste.
Typische Markierungen sind „Welches Modul?“, „Mit welchem Konto?“, „Was bedeutet diese Spalte?“ und „Darf ich die Datei weitergeben?“. Jede davon ist ein fehlender Satz.
Die Gegenprobe durch Lesen ersetzt keinen Lauf im Testtenant. Aber sie findet die meisten Lücken, bevor jemand anderes darüber stolpert.
Meine Empfehlung. Nimm dir eine deiner eigenen Anleitungen vor, nicht eine fremde. Bei der eigenen siehst du die Lücken am schlechtesten, weil du sie im Kopf automatisch füllst.
Welche deiner Anleitungen würde den Test mit den zwölf Punkten bestehen?
Gruß Micha