Suche

Frag mich alles

Code-Dokumentation mit Dokumenten erstellen

Erstelle und pflege schnell Dokumentation über deinen Code oder die von dir entwickelten Features!

Erfahre, wie Alex mithilfe von Dokumenten das Team dabei unterstützt hat, Features schneller zu verbessern.

Lerne Alex kennen

Alex ist eine erfahrene Entwicklerin bei einem cloudbasierten Softwareunternehmen. Sie stellt fest, dass einige Features nur sehr spärlich dokumentiert sind.

Alex bemerkt, dass das Team einen Großteil seiner Zeit damit verbringt, direkt im Code der Software nachzuvollziehen, wie Features funktionieren. Das verlangsamt das Team darin, bestehende Features zu verbessern.

Die Herausforderung

Das Produkt- und Entwicklungsteam arbeitet nach einem sehr straffen Zeitplan, um Features in das Produkt zu bringen. Die Entwicklerinnen und Entwickler haben kaum Zeit, Dokumentation zu neuen Features zu erstellen.

Das Team hat keine Zeit, die Dokumentation aktuell zu halten, während ein Feature weiterentwickelt und Fehler behoben werden.

Einige neuere Entwicklerinnen und Entwickler sind frustriert über den Mangel an Dokumentation. Es fällt ihnen schwer, das Produkt auf effektive Weise kennenzulernen.

Andere Entwicklerinnen und Entwickler haben das Gefühl, mehr Zeit mit dem Beantworten von Fragen zu verbringen als mit dem Lösen von Problemen und dem Schreiben von besserem Code.

Die Lösung

Alex arbeitet gerade daran, ein Feature zu verbessern, das keine gute Dokumentation hat. Sie entscheidet sich, ein ClickUp-Dokument mit Informationen über das Feature als Referenzmaterial für andere Entwicklerinnen und Entwickler zu erstellen.

Dokument und Seitenstruktur erstellen

Alex entscheidet, dass jedes Feature sein eigenes Dokument haben soll. Wenn das Team an einem Feature arbeitet, befinden sich alle relevanten Informationen in einem einzigen, in sich geschlossenen Dokument.

Durch die Verwendung von Seiten innerhalb eines Dokuments kann das Team schnell relevante Antworten finden, ohne separate Dokumente suchen und durchsuchen zu müssen.

Alex erstellt einige Seiten innerhalb des Dokuments, um die Inhalte danach zu strukturieren, was das Team wissen muss und wonach es suchen könnte.

  1. Produktzusammenfassung
  2. Frontend-Code
  3. Backend-Code
  4. Infrastruktur
  5. Mobile App
  6. Tests und QA
  7. FAQ und Fehlerbehebung

Überschriften

Unter jeder Seite legt Alex Überschriften fest, damit dem Entwicklungsteam klar ist, welche Informationen wohin gehören.

Produktzusammenfassung

  • Produkt-Briefing
  • Feature-Übersicht
  • Anwendungsfälle
  • UI-Design

Frontend

  • UI-Elemente
  • Stile
  • Tooltips

Backend

  • API-Routen
  • Datenbankschema

Mobile

  • iOS
  • Android

Tests und QA

  • Akzeptanzkriterien
  • Automatisierte QA-Tests

Formatierung

Alex nutzt eine Kombination der in ClickUp Docs verfügbaren Formatierungsoptionen, um der Dokumentation ein einheitliches Erscheinungsbild zu geben.

Inline-Code und Codeblöcke

Alex verwendet Backticks ( ` ), um Text als Inline-Code zu formatieren und einzelne Codezeilen anzuzeigen, wie im folgenden Beispiel zu sehen:

Screenshot der Inline-Code-Formatierung

Für größere Code-Ausschnitte verwendet Alex die Codeblock-Formatierung ( /co ), wie unten gezeigt:

Screenshot der Codeblock-Formatierung

Formatierungsoptionen für Codeblöcke

Lege für deinen Codeblock die Programmiersprache deiner Wahl fest!

  1. Fahre mit der Maus über die obere rechte Ecke
  2. Wähle deine bevorzugte Sprache aus

Inhalte verknüpfen und einbetten

Das Dokument von Alex enthält jetzt Text, einige Screenshots und hilfreiche Code-Ausschnitte.

Es sieht schon gut aus, aber die Produktzusammenfassung ist noch leer.

Das Produktteam verwendet Figma, um die Benutzeroberfläche zu gestalten und Wireframes zu erstellen. Alex verwendet den Slash-Befehl /figma, um das aktualisierte Design des Features direkt auf der Seite der Produktzusammenfassung einzubetten.

Alex verwendet eine @@-Erwähnung, um die Verknüpfung zur Epic-Aufgabe auf der Team-Roadmap herzustellen.

Eine Vorlage erstellen

Alex speichert die Dokumentgliederung als Vorlage, damit das Team schnell und einfach ein Dokument mit den Unterseiten und Überschriften für andere Features erstellen kann.

  1. Klicke auf das Einstellungssymbol des Dokuments in der rechten Seitenleiste
  2. Wähle Als Vorlage speichern aus

Alex füllt ein Beispieldokument mithilfe der Vorlage aus, damit das Team einen Goldstandard für Dokumentation als Referenz hat.

Alex erstellt ein neues Dokument auf Basis der Vorlage, füllt es aus und teilt es mit dem Team.

Proof of Concept

Alex stellt das Konzept der Dokumentvorlage beim nächsten Teammeeting dem Entwicklungsteam vor. Die anderen Entwicklerinnen und Entwickler sind begeistert von Alex' detailliertem Dokumentationsbeispiel!

Das Team fragt sich, wie lange es dauern könnte, alle Details auszufüllen. Alex fordert sie auf, ein Feature auszuwählen, um allen zu zeigen, wie schnell sich Dokumentation erstellen lässt.

Das Team entscheidet sich für ein Feature. Alex erstellt ein Dokument, wendet die Vorlage mithilfe des Slash-Befehls /temp an und teilt den Link mit allen im Call.

Einige Entwicklerinnen und Entwickler steigen ein und beginnen, das Dokument gemeinsam mit Alex zu bearbeiten. Alle füllen die Seiten und Abschnitte aus, mit denen sie am besten vertraut sind.

Das gesamte Team ist angenehm überrascht: Nach nur 20 Minuten haben sie einen recht umfassenden Dokumentationsentwurf erstellt.

Das Ergebnis

Das Team beschließt, Alex' Vorlage und Dokumentation in einem Testlauf auszuprobieren. Im nächsten Sprint verbringen einige Entwicklerinnen und Entwickler 30 Minuten damit, die Dokumentation für das Hauptfeature auszufüllen.

Die Dokumentation ist noch nicht ganz fertig. Es gibt eine grobe Gliederung mit gerade genug Details, damit andere Entwicklerinnen und Entwickler das Feature verstehen und verbessern können.

Nach einigen Wochen ist das Schreiben von Dokumentation zu einem festen Bestandteil der Aufgaben des Entwicklungsteams geworden.

Mit einigen Anpassungen und Verbesserungen an Alex' Vorlage sinkt der Zeitaufwand für das Erstellen und Pflegen von Dokumentation.

Alex verschickt eine Umfrage und stellt fest, dass:

  • Neuere Entwicklerinnen und Entwickler sich sicherer fühlen, mit dem Code zu arbeiten, wenn Dokumentation vorhanden ist
  • Erfahrene Entwicklerinnen und Entwickler weniger Fragen von Kolleginnen und Kollegen sowie vom Kundensupport-Team erhalten

Das ist ein großer Erfolg für das Entwicklungsteam! Bei einem Team-Event wird Alex der Ehrentitel „Resident Librarian and the keeper of knowledge" verliehen.