Generare la documentazione del progetto usando GitHub Copilot

  • 6 minuti

La documentazione del progetto descrive lo scopo, gli obiettivi e i requisiti di un progetto. Per creare la documentazione del progetto, è necessario comprendere la struttura del progetto, i relativi componenti e il modo in cui i componenti interagiscono tra loro.

La vista Chat di GitHub Copilot è uno strumento ideale per generare la documentazione del progetto, perché può analizzare l'intera struttura e fornire panoramiche di alto livello. La visualizzazione Chat può essere usata anche per generare tipi specifici di documentazione, ad esempio file README, riferimenti API e altri documenti correlati al progetto.

È possibile usare ognuna delle modalità di visualizzazione chat (Ask, Agent o Plan) per generare la documentazione del progetto. Ogni modalità ha i propri punti di forza e debolezza. Le specifiche del progetto e altri vincoli influiscono sulla modalità da usare.

Importante

Quando si usa la visualizzazione chat in modalità agente, ogni richiesta viene considerata come richiesta premium, moltiplicata per il moltiplicatore del modello. GitHub Copilot potrebbe eseguire diverse azioni di completamento dell'attività, ma queste azioni di completamento non vengono conteggiate per l'utilizzo delle richieste premium. Vengono fatturati solo i prompt immessi. Le richieste Premium totali usate dipendono dal numero di richieste immesse e dal modello selezionato.

Stabilire i requisiti della documentazione del progetto

I tipi di documentazione e i requisiti di contenuto dipendono dal progetto, dai consumer previsti e dagli standard adottati dall'organizzazione.

Ad esempio, il README.md potrebbe includere le sezioni seguenti:

  • Titolo progetto: nome del progetto.
  • Descrizione: breve panoramica del funzionamento del progetto e del motivo per cui esiste.
  • Sommario: facoltativo, ma utile per letture più lunghe.
  • Installazione: istruzioni su come installare e configurare il progetto.
  • Utilizzo: esempi di come usare il progetto, inclusi frammenti di codice o screenshot.
  • Funzionalità: elenco delle funzionalità o delle funzionalità principali.
  • Configurazione: informazioni dettagliate sulle opzioni di configurazione o sulle variabili di ambiente.
  • Contributi: linee guida per contribuire al progetto.
  • Licenza: tutte le licenze usate dal progetto distribuito.
  • Crediti e riconoscimenti: riconoscimento di collaboratori, librerie o risorse usate.
  • Contatto: come raggiungere i gestori o il team di progetto.
  • Log delle modifiche: cronologia delle modifiche e degli aggiornamenti (talvolta collegati a un file separato).

GitHub Copilot Chat consente di generare la documentazione del progetto che soddisfi le esigenze specifiche del progetto e degli stakeholder.

Usare la modalità Ask agent per generare la documentazione del progetto

La modalità agente Ask può essere usata per analizzare un'area di lavoro e quindi generare la documentazione.

Usare il processo seguente per generare la documentazione del progetto usando la modalità Ask agent:

  1. Identificare i requisiti della documentazione e le risorse di supporto.

    • Identificare i requisiti della documentazione per il progetto. Identificare i tipi di documentazione e le sezioni del documento necessarie.

    • Identificare le risorse necessarie per generare la documentazione. L'area di lavoro del codice potrebbe essere l'unica risorsa necessaria. Tuttavia, potrebbe essere necessario aggiungere contesto alla chat per sezioni come "Contributi", "Crediti" e "Contatto".

  2. Aprire la visualizzazione Chat e avviare una nuova sessione di chat usando la modalità Chiedi agente.

  3. Aggiungere contesto alla sessione di chat.

    • È possibile aggiungere contesto alla sessione di chat trascinando e rilasciando file dalla visualizzazione EXPLORER di Visual Studio Code nella visualizzazione Chat. È anche possibile usare il pulsante Associa contesto (icona di graffetta).
    • È possibile aprire file esterni nell'editor di codice per includere risorse che non fanno parte dell'area di lavoro e usarle per fornire più contesto. Ad esempio, è possibile aprire file markdown contenenti linee guida per i collaboratori o informazioni di contatto e quindi usare il pulsante Associa contesto per aggiungerli al contesto di visualizzazione Chat.

  4. Immettere una serie di richieste che esaminano i requisiti della documentazione.

    È possibile usare la modalità Ask agent per analizzare l'area di lavoro e creare una cronologia delle sessioni di chat che supporti i requisiti della documentazione. La descrizione degli obiettivi può aiutare a stabilire il contesto per la sessione di chat. Porre domande che rispondono ai requisiti consente di GitHub Copilot identificare le informazioni necessarie per generare la documentazione.

    Aggiornare il contesto aggiunto in base alle esigenze.

  5. Immettere un prompt che richiede la documentazione suggerita del progetto, elencando le sezioni necessarie identificate nel primo passaggio.

    Ad esempio: "@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. Esaminare la documentazione del progetto suggerita e perfezionare i risultati usando nuove richieste, se necessario.

  7. Spostare la documentazione suggerita del progetto in un file di documentazione del progetto.

    Ad esempio, creare un file README.md nella radice dell'area di lavoro e inserire il contenuto suggerito nel file.

    È possibile usare la modalità Ask agent per suggerire aggiornamenti per sezioni specifiche del progetto dopo la creazione del documento o usare altri strumenti di GitHub Copilot per facilitare gli aggiornamenti.

Usare la modalità Piano per generare la documentazione del progetto

La modalità di piano è ideale per creare un piano di implementazione dettagliato prima di generare la documentazione del progetto. La modalità piano analizza la codebase, identifica i requisiti della documentazione e produce un piano dettagliato. Dopo aver approvato il piano, è possibile passare alla modalità agente per l'esecuzione.

Usare il processo seguente per generare la documentazione del progetto, ad esempio un file README.md, usando la modalità Piano:

  1. Identificare i requisiti della documentazione e le risorse di supporto.

  2. Aprire la visualizzazione Chat e avviare una nuova sessione di chat usando la modalità Piano.

  3. Inserisci un prompt che descriva il tuo compito di documentazione.

    Ad esempio: "È necessario creare un file README e la documentazione di supporto per questo progetto. Il file README deve includere: Titolo del progetto, Descrizione, Sommario, Installazione, Utilizzo, Funzionalità, Configurazione e Licenza."

  4. Esaminare il piano di implementazione.

    Dopo alcuni istanti, l'agente del piano restituisce un piano nell'interfaccia della chat. Il piano fornisce un riepilogo generale e una suddivisione dei passaggi, incluse eventuali domande aperte per chiarimenti. È possibile scorrere più volte per chiarire i requisiti, regolare l'ambito o rispondere alle domande.

  5. Al termine del piano, selezionare Avvia implementazione per distribuire il piano in modalità agente oppure selezionare Apri nell'editor per salvare il piano come file Markdown per usarlo in un secondo momento.

    Quando si seleziona Avvia implementazione, GitHub Copilot passa alla modalità agente e inizia a implementare la documentazione in base al piano approvato. Esaminare i file di documentazione generati e accettare o eliminare le modifiche.

Usare la modalità agente per generare la documentazione del progetto

La modalità agente è ideale per generare la documentazione del progetto che richiede una conoscenza approfondita del progetto. La modalità Agente analizza l'intera struttura del progetto prima di generare la documentazione del progetto. Raccogliendo informazioni da più file e cartelle, la modalità agente può descrivere relazioni complesse e includere collegamenti tra documenti.

Usare il processo seguente per generare la documentazione del progetto, ad esempio README.md file, usando la modalità agente:

  1. Identificare i requisiti della documentazione e le risorse di supporto.

  2. Aprire la visualizzazione Chat e avviare una nuova sessione di chat usando la modalità agente.

  3. Aggiungere contesto alla sessione di chat.

    I partecipanti alla chat non sono disponibili in modalità agente, quindi non è possibile specificare @workspace come parte della richiesta. Tuttavia, è possibile aggiungere contesto alla sessione di chat usando #codebase e aggiungendo file e cartelle dell'area di lavoro al contesto della chat. I file esterni possono essere aperti in Visual Studio Code e quindi aggiunti al contesto della chat usando il pulsante Attach Context.

  4. Immettere un prompt per creare la documentazione del progetto desiderata.

    Ad esempio: "Generare una raccolta di file di documentazione del progetto. Creare o aggiornare il file README.md dell'area di lavoro per questo repository. Creare o aggiornare il file UsageExamples.md. Creare o aggiornare il file ChangeLog.md. Includere collegamenti tra i file della documentazione, classi e metodi di riferimento incrociati e garantire la coerenza tra i documenti."

  5. Esaminare i file di documento e quindi salvare o rimuovere gli aggiornamenti.

    Aggiornare il file usando le richieste per correggere o migliorare sezioni specifiche, se necessario.

Funzionalità della modalità agente

Esistono diverse attività della documentazione in cui la modalità agente è la scelta migliore.

  1. Generazione di documentazione multifile e interfile.

    • La modalità agente può analizzare l'intera struttura del progetto, raccogliere informazioni da più file e cartelle e generare la documentazione che collega e riepiloga il contenuto nella codebase. Ad esempio, la generazione di un riferimento API completo o un file README che descrive tutti i componenti principali.

  2. Analisi e riepilogo automatizzati dei progetti.

    • La modalità agente può eseguire attività come riepilogare l'architettura, identificare classi/servizi principali e produrre diagrammi o tabelle che richiedono la comprensione delle relazioni tra file e componenti.

  3. Generazione di contenuto dinamico (ad esempio, esempi di utilizzo, tabelle di classi)

    • La modalità agente può analizzare il progetto per generare esempi di utilizzo, tabelle di responsabilità delle classi o elenchi di API pubbliche.

  4. Attività di documentazione in batch.

    • La modalità agente può eseguire una sequenza di attività della documentazione (ad esempio, aggiornare README, creare CONTRIBUTING.md, generare documenti API, aggiornare il log delle modifiche) in un flusso di lavoro.

  5. Collegamento intelligente e navigazione.

    • La modalità agente può creare collegamenti tra file di documentazione, classi e metodi di riferimento incrociati e garantire la coerenza tra documenti.

La modalità agente è ideale per attività di documentazione a livello di progetto, multi-file e con riconoscimento del contesto che richiedono analisi, sintesi e coordinamento.

Riassunto

GitHub Copilot consente di generare la documentazione del progetto che soddisfi le esigenze specifiche del progetto e dei relativi stakeholder. La visualizzazione Chat può essere usata per generare la documentazione del progetto in tre modalità diverse: Ask, Agent e Plan. Ogni modalità ha i propri punti di forza e debolezza, e la modalità migliore da usare dipende dall'attività specifica a portata di mano. La modalità Ask agent è ideale per porre domande sui concetti relativi alla codebase o alla tecnologia. La modalità Agent è ideale per generare la documentazione del progetto che richiede una conoscenza approfondita del progetto. La modalità Piano è ideale per la creazione di un piano di implementazione dettagliato prima della generazione della documentazione, che può quindi essere passata alla modalità Agente per l'esecuzione.