Generieren der Projektdokumentation mit GitHub Copilot

  • 6 Minuten

In der Projektdokumentation werden der Zweck, die Ziele und die Anforderungen eines Projekts beschrieben. Zum Erstellen der Projektdokumentation müssen Sie die Projektstruktur, die zugehörigen Komponenten und die Interaktion der Komponenten verstehen.

Die Chatansicht von GitHub Copilot ist ein ideales Tool zum Generieren von Projektdokumentationen, da sie die gesamte Projektstruktur analysieren und allgemeine Übersichten über das Projekt bereitstellen kann. Die Chatansicht kann auch verwendet werden, um bestimmte Arten von Dokumentationen zu generieren, z. B. README-Dateien, API-Verweise und andere projektbezogene Dokumente.

Sie können jeden der Chatansichtsmodi (Fragen, Bearbeiten oder Agent) verwenden, um Projektdokumentation zu generieren. Jeder Modus hat seine eigenen Stärken und Schwächen. Projektspezifikationen und andere Einschränkungen wirken sich darauf aus, welcher Modus verwendet werden soll.

Von Bedeutung

Wenn Sie die Chatansicht im Agentmodus verwenden, kann GitHub Copilot mehrere Premium-Anforderungen stellen, um eine einzelne Aufgabe abzuschließen. Premium-Anfragen können durch benutzerinitiierte Eingabeaufforderungen und Folgeaktionen verwendet werden, die Copilot in Ihrem Auftrag ausführt. Die gesamtzahl der verwendeten Premiumanforderungen hängt von der Komplexität des Vorgangs, der Anzahl der beteiligten Schritte und dem ausgewählten Modell ab.

Einrichten von Projektdokumentationsanforderungen

Dokumentationstypen und Inhaltsanforderungen hängen vom Projekt, den beabsichtigten Verbrauchern und den von der Organisation angenommenen Standards ab.

Die README.md können z. B. die folgenden Abschnitte enthalten:

  • Projekttitel: Der Name Ihres Projekts.
  • Beschreibung: Eine kurze Übersicht darüber, was das Projekt tut und warum es vorhanden ist.
  • Inhaltsverzeichnis: Optional, aber hilfreich für längere READMEs.
  • Installation: Anweisungen zum Installieren und Einrichten des Projekts.
  • Verwendung: Beispiele für die Verwendung des Projekts, einschließlich Codeausschnitte oder Screenshots.
  • Features: Eine Liste der wichtigsten Features oder Funktionen.
  • Konfiguration: Details zu konfigurationsoptionen oder Umgebungsvariablen.
  • Mitwirkend: Richtlinien für einen Beitrag zum Projekt.
  • Lizenz: Alle Lizenzen, die vom verteilten Projekt verwendet werden.
  • Danksagungen und Anerkennungen: Anerkennung von Mitwirkenden, Bibliotheken oder Ressourcen.
  • Kontakt: So erreichen Sie die Betreuer oder das Projektteam.
  • Changelog: Ein Verlauf von Änderungen und Aktualisierungen (manchmal mit einer separaten Datei verknüpft).

GitHub Copilot Chat kann Ihnen helfen, Projektdokumentationen zu generieren, die den spezifischen Anforderungen Ihres Projekts und seiner Projektbeteiligten entsprechen.

Verwenden des Fragemodus zum Generieren der Projektdokumentation

Der Fragemodus kann verwendet werden, um einen Arbeitsbereich zu analysieren und dann Dokumentation zu generieren.

Verwenden Sie den folgenden Prozess, um die Projektdokumentation mithilfe des Fragemodus zu generieren:

  1. Identifizieren Sie die Dokumentationsanforderungen und unterstützenden Ressourcen.

    • Identifizieren Sie die Dokumentationsanforderungen für Ihr Projekt. Identifizieren Sie die Arten der Dokumentation und die erforderlichen Dokumentabschnitte.

    • Identifizieren Sie die Ressourcen, die zum Generieren der Dokumentation erforderlich sind. Ihr Codearbeitsbereich könnte die einzige erforderliche Ressource sein. Möglicherweise müssen Sie dem Chat jedoch Kontext für Abschnitte wie "Mitwirken", "Gutschriften" und "Kontakt" hinzufügen.

  2. Öffnen Sie die Chatansicht, und starten Sie eine neue Chatsitzung mithilfe des Fragemodus.

  3. Fügen Sie der Chatsitzung Kontext hinzu.

    • Sie können der Chatsitzung Kontext hinzufügen, indem Sie Dateien aus der EXPLORER-Ansicht von Visual Studio Code in die Chatansicht ziehen und ablegen. Sie können auch die Schaltfläche " Kontext hinzufügen " verwenden.
    • Sie können externe Dateien im Code-Editor öffnen, um Ressourcen einzuschließen, die nicht Teil des Arbeitsbereichs sind, und diese verwenden, um mehr Kontext bereitzustellen. Sie können beispielsweise Markdowndateien öffnen, die Mitwirkenderichtlinien oder Kontaktinformationen enthalten, und dann die Schaltfläche " Kontext hinzufügen " verwenden, um sie dem Kontext der Chatansicht hinzuzufügen.

  4. Geben Sie eine Reihe von Eingabeaufforderungen ein, die Ihre Dokumentationsanforderungen untersuchen.

    Sie können den Fragemodus verwenden, um den Arbeitsbereich zu analysieren und einen Chatsitzungsverlauf zu erstellen, der Ihre Dokumentationsanforderungen unterstützt. Wenn Sie Ihre Ziele beschreiben, können Sie den Kontext für die Chatsitzung einrichten. Wenn Sie Fragen stellen, die Ihre Anforderungen erfüllen, hilft GitHub Copilot, die informationen zu identifizieren, die zum Generieren der Dokumentation erforderlich sind.

    Aktualisieren Sie den hinzugefügten Kontext nach Bedarf.

  5. Geben Sie eine Eingabeaufforderung ein, die nach der vorgeschlagenen Projektdokumentation fragt und die erforderlichen Abschnitte auflistet, die Sie im ersten Schritt identifiziert haben.

    Beispiel: "@workspace /explain I need help creating a README file that can be used in the GitHub repository for this workspace. The file should be formatted as markdown. The README file needs to include the following sections: Project Title, Description, Table of Contents, Installation, Usage, Features, Configuration, and License."

  6. Überprüfen Sie die vorgeschlagene Projektdokumentation, und verfeinern Sie die Ergebnisse bei Bedarf mithilfe neuer Eingabeaufforderungen.

  7. Verschieben Sie die vorgeschlagene Projektdokumentation in eine Projektdokumentationsdatei.

    Erstellen Sie beispielsweise eine README.md Datei im Stammverzeichnis des Arbeitsbereichs, und fügen Sie den vorgeschlagenen Inhalt in die Datei ein.

    Sie können den Fragemodus verwenden, um Aktualisierungen für bestimmte Abschnitte Ihres Projekts nach dem Erstellen des Dokuments vorzuschlagen oder andere GitHub Copilot-Tools zur Unterstützung von Updates zu verwenden.

Verwenden des Bearbeitungsmodus zum Generieren der Projektdokumentation

Der Bearbeitungsmodus eignet sich am besten für Änderungen an bestimmten Dateien im Projekt. Der Bearbeitungsmodus kann zum Generieren der Projektdokumentation verwendet werden, indem kontextbezogene Dateien zum Chat hinzugefügt und dann Dokumentationsdateien erstellt oder aktualisiert werden.

Verwenden Sie den folgenden Prozess, um projektdokumentation zu generieren, z. B. README.md Datei, mithilfe des Bearbeitungsmodus:

  1. Identifizieren Sie die Dokumentationsanforderungen und unterstützenden Ressourcen.

  2. Öffnen Sie die Chatansicht, und starten Sie eine neue Chatsitzung mit dem Bearbeitungsmodus.

  3. Fügen Sie der Chatsitzung Kontext hinzu.

    Chatteilnehmer sind im Bearbeitungsmodus nicht verfügbar, daher können Sie sie nicht als Teil Ihrer Eingabeaufforderung angeben @workspace . Sie können jedoch der Chatsitzung Kontext hinzufügen, indem Sie #codebase verwenden und Dateien oder Ordner aus der EXPLORER-Ansicht von Visual Studio Code in die Chat-Ansicht ziehen und ablegen. Verwenden Sie Visual Studio Code, um externe Dateien zu öffnen, z. B. Markdowndateien, die Mitwirkenderichtlinien enthalten, und verwenden Sie dann die Schaltfläche " Kontext hinzufügen ", um sie dem Chatkontext hinzuzufügen.

  4. Geben Sie eine Eingabeaufforderung ein, um die beabsichtigte Projektdokumentation zu erstellen.

    Beispiel: "Ich muss eine README-Datei erstellen, die für das GitHub-Repository verwendet werden kann. Die Datei sollte als Markdown formatiert werden. Erstellen Sie eine README.md Datei im Stammarbeitsbereichsordner. Die README-Datei muss die folgenden Abschnitte enthalten: Projekttitel, Beschreibung, Inhaltsverzeichnis, Installation, Verwendung, Features, Konfiguration und Lizenz."

  5. Überprüfen Sie die README.md Datei, die im Bearbeitungsmodus erstellt wurde, und speichern oder verwerfen Sie die Datei.

    Sie können die Datei mithilfe von Eingabeaufforderungen aktualisieren, um bestimmte Abschnitte bei Bedarf zu korrigieren oder zu verbessern.

Verwenden des Agentmodus zum Generieren der Projektdokumentation

Der Agentmodus eignet sich am besten zum Generieren von Projektdokumentationen, die ein fundiertes Verständnis des Projekts erfordern. Der Agentmodus analysiert die gesamte Projektstruktur, bevor die Projektdokumentation generiert wird. Durch das Sammeln von Informationen aus mehreren Dateien und Ordnern kann der Agentmodus komplexe Beziehungen beschreiben und Verknüpfungen zwischen Dokumenten enthalten.

Verwenden Sie den folgenden Prozess, um projektdokumentation zu generieren, z. B. README.md Datei, mithilfe des Bearbeitungsmodus:

  1. Identifizieren Sie die Dokumentationsanforderungen und unterstützenden Ressourcen.

  2. Öffnen Sie die Chatansicht, und starten Sie eine neue Chatsitzung mit dem Agentmodus.

  3. Fügen Sie der Chatsitzung Kontext hinzu.

    Chatteilnehmer sind im Agentmodus nicht verfügbar, daher können Sie sie nicht als Teil Ihrer Eingabeaufforderung angeben @workspace . Sie können jedoch der Chatsitzung Kontext hinzufügen, indem Sie #codebase sowie Arbeitsbereichsdateien und Ordner zum Chatkontext hinzufügen. Externe Dateien können in Visual Studio Code geöffnet und dann mithilfe der Schaltfläche " Kontext hinzufügen " zum Chatkontext hinzugefügt werden.

  4. Geben Sie eine Eingabeaufforderung ein, um die beabsichtigte Projektdokumentation zu erstellen.

    Beispiel: "Generieren einer Sammlung von Projektdokumentationsdateien. Erstellen oder aktualisieren Sie die README.md-Datei des Arbeitsbereichs für dieses Repository. Erstellen oder aktualisieren Sie die UsageExamples.md Datei. Erstellen oder aktualisieren Sie die ChangeLog.md Datei. Fügen Sie Verknüpfungen zwischen den Dokumentationsdateien, referenzübergreifenden Klassen und Methoden ein, und sorgen Sie für Konsistenz in den Dokumenten."

  5. Überprüfen Sie die Dokumentdateien, und speichern oder verwerfen Sie die Aktualisierungen.

    Aktualisieren Sie die Datei mithilfe von Eingabeaufforderungen, um bestimmte Abschnitte bei Bedarf zu korrigieren oder zu verbessern.

Funktionen für den Agentmodus

Es gibt mehrere Dokumentationsaufgaben, bei denen der Agentmodus die beste Wahl ist.

  1. Mehrdateiige und dateiübergreifende Dokumentationsgenerierung.

    • Der Agentmodus kann die gesamte Projektstruktur analysieren, Informationen aus mehreren Dateien und Ordnern sammeln und Dokumentation generieren, die Inhalte über die Codebasis hinweg verknüpft und zusammenfasst. Ror-Beispiel: Generieren eines vollständigen API-Verweises oder einer README, die alle hauptkomponenten beschreibt.

  2. Automatisierte Projektanalyse und Zusammenfassung.

    • Der Agentmodus kann Aufgaben wie das Zusammenfassen der Architektur, das Identifizieren von Hauptklassen/Diensten und das Erstellen von Diagrammen oder Tabellen ausführen, die beziehungen zwischen Dateien und Komponenten verstehen müssen.

  3. Dynamische Inhaltsgenerierung (z. B. Verwendungsbeispiele, Klassentabellen)

    • Der Agentmodus kann das Projekt scannen, um Verwendungsbeispiele, Klassenverantwortungstabellen oder Listen öffentlicher APIs zu generieren.

  4. Chargendokumentations-Aufgaben.

    • Der Agentmodus kann eine Folge von Dokumentationsaufgaben (z. B. README aktualisieren, CONTRIBUTING.md erstellen, API-Dokumente generieren, Änderungsprotokoll aktualisieren) in einem Workflow ausführen.

  5. Intelligente Verknüpfung und Navigation.

    • Der Agentmodus kann Verknüpfungen zwischen Dokumentationsdateien, referenzübergreifenden Klassen und Methoden erstellen und die Konsistenz zwischen Dokumenten sicherstellen.

Der Agentmodus eignet sich ideal für projektweite, dateiübergreifende und kontextbezogene Dokumentationsaufgaben, die Analysen, Synthese und Koordination erfordern.

Zusammenfassung

GitHub Copilot kann Ihnen helfen, Projektdokumentationen zu generieren, die den spezifischen Anforderungen Ihres Projekts und seiner Projektbeteiligten entsprechen. Die Chatansicht kann verwendet werden, um Projektdokumentation in drei verschiedenen Modi zu generieren: Fragen, Bearbeiten und Agent. Jeder Modus hat seine eigenen Stärken und Schwächen, und der beste zu verwendende Modus hängt von der jeweiligen Aufgabe ab. Der Fragemodus eignet sich am besten, um Fragen zu Ihren Codebasis- oder Technologiekonzepten zu stellen. Der Bearbeitungsmodus eignet sich am besten für Änderungen an bestimmten Dateien im Projekt. Der Agentmodus eignet sich am besten zum Generieren von Projektdokumentationen, die ein ausführliches Verständnis des Projekts erfordern.