Zum Inhalt springen
Zurück zum Blog

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.

Microsoft 365Sysadmin
Eine M365-Anleitung schreiben, die andere wirklich nachbauen können.

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.

AbschnittInhalt
KopfTitel, Stand, im Tenant gelaufen ja oder nein
WozuZiel und Nicht-Ziel in zwei Sätzen
Für wenZielgruppe, Vorkenntnisse
Was du brauchstRolle, Berechtigungen, Werkzeuge, Lizenzen, Eingaben mit Fundort
Was dabei passiertLiest oder ändert, was zurückbleibt
SchritteNummeriert, je Schritt Aktion und erwartetes Ergebnis
Ergebnis kontrollierenWie die richtige Ausgabe aussieht, woran du Lücken erkennst
Wenn etwas schiefgehtHäufige Fehler und ihre Bedeutung
AufräumenRü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

Hat dir der Artikel geholfen? Teile ihn mit deinem Netzwerk.

LinkedIn X