Documentation et Google Workspace : Guide Pratique pour Développeurs

#

Introduction

#

La documentation est un pilier essentiel de tout projet de développement logiciel. Elle permet de transmettre la connaissance, faciliter la collaboration et garantir la pérennité du code. Dans cet article, nous explorerons comment utiliser Google Workspace pour créer, organiser et maintenir une documentation efficace en équipe.

Pourquoi Documenter Efficacement ?

#

Les Quatre Piliers de la Documentation

#

    graph TD
    A[Documentation Efficace] --> B[Compréhension du contexte métier]
    A --> C[Clarification des attentes techniques]
    A --> D[Facilitation de l'estimation]
    A --> E[Réduction des allers et retours]
    
    B --> F[Gain de temps pour l'équipe]
    C --> F
    D --> F
    E --> F

Questions Essentielles à se Poser

#

Lors de la rédaction de documentation, posez-vous systématiquement ces questions :

“Qu’est-ce qu’un développeur aurait besoin de savoir ?”

Réflexions à avoir :

• Quel est le contexte métier ?
• Quelles sont les contraintes techniques ?
• Quelles sont les dépendances externes ?
• Quels sont les cas limites ?

“Qu’est-ce que j’aurais aimé qu’on me laisse pour avancer plus rapidement ?”

Éléments utiles :

• Exemples concrets d’utilisation
• Diagrammes d’architecture
• Spécifications des API
• Données de test
• Procédures de déploiement

Permettre à d’Autres Développeurs de Gagner du Temps

#

La documentation doit éviter de perdre du temps lors d’éventuelles mises à jour. Une bonne documentation :

• Est maintenable dans le temps
• Évite la redondance
• Reste à jour avec le code
• Est facilement accessible

Méthodologie INVEST pour la Documentation

#

Critères INVEST Appliqués à la Documentation

#

La méthode INVEST, traditionnellement utilisée pour les User Stories, s’applique également à la documentation :

Maintenir Maîtrisée la Documentation

#

“L’utilisateur veut changer ses notifications, créer la page de gestion des préférences”

Cette user story peut être décomposée en documentation :

Pour la nécessiter, le chaque écrite ce que vous avez reporté des modifications :

• Quand ? (Date de modification)
• Qui ? (Auteur de la modification)
• Pourquoi ? (Raison de la modification / lien)
• Quoi ? (Ce qui a été modifié en termes de fonctionnalité)
• Comment ? (Vérifier à travers le processus de la fonctionnalité)
• Pourquoi ? (Pour gérer cette modification)

User Stories et Complexité

#

Structure d’une User Story

#

Une User Story répond à trois questions fondamentales :

En tant que [QUI ?]
Je veux [QUOI ?]
Afin de [POURQUOI ?]

Exemple concret :

En tant qu'administrateur RH
Je veux exporter le profil d'un employé en PDF
Afin de générer les documents contractuels

Estimation de la Complexité

#

La complexité d’une User Story suit généralement la suite de Fibonacci :

1, 2, 3, 5, 8, 13, 21…

DoD (Definition of Done) et DoR (Definition of Ready)

#

Definition of Ready (DoR)

#

Critères pour qu’une User Story soit prête à être développée :

• User Story rédigée selon le format “En tant que… Je veux… Afin de…”
• Critères d’acceptation définis
• Complexité estimée
• Dépendances identifiées
• Maquettes disponibles (si nécessaire)

Definition of Done (DoD)

#

Critères pour considérer une User Story comme terminée :

• Code développé et testé
• Tests unitaires écrits et passants
• Documentation mise à jour
• Code review effectuée
• Déployé en environnement de test
• Validation par le Product Owner

Google Workspace pour la Documentation

#

Cas d’Usage : User Story US-256

#

markdown[US-256] En tant qu'"Administrateur RH"
Je souhaite exporter le profil d'un employé en PDF
Afin de générer les documents contractuels

Business Context

#

Les équipes RH passent actuellement 2h par jour en copier/coller des informations des collaborateurs dans des “modèles” Word. Cette amélioration permettra de gagner 80% de temps/homme.

Scénarios

#

Scénario “Export réussi”

#

L’utilisateur se connecte avec un compte administrateur Il accède à la liste des employés Il clique sur “Exporter en PDF” pour un employé Le système génère un PDF avec toutes les informations Le PDF est téléchargé automatiquement

Scénario “Informations manquantes”

#

L’utilisateur tente d’exporter un profil incomplet Le système affiche un message d’erreur Le système liste les champs obligatoires manquants

Conception

#

Éléments techniques à documenter :

• Librairies utilisées (ex: jsPDF, PDFKit)
• Versions des dépendances
• Template PDF à utiliser
• Mapping des données

Tests

#

Données de test à préparer pour les deux scénarios :

{
  "scenario": "export_reussi",
  "employee": {
    "id": "EMP001",
    "firstName": "Jean",
    "lastName": "Dupont",
    "email": "jean.dupont@example.com",
    "position": "Développeur Senior",
    "department": "IT"
  }
}

{
  "scenario": "informations_manquantes",
  "employee": {
    "id": "EMP002",
    "firstName": "Marie",
    "email": null,
    "position": "Designer"
  }
}

Diagramme DoD (Definition of Done)

#

    graph TD
    A[DoD - Definition of Done] --> B[Développement]
    A --> C[Tests]
    A --> D[Documentation]
    A --> E[Déploiement]
    
    B --> B1[Code écrit]
    B --> B2[Code review OK]
    
    C --> C1[Tests unitaires]
    C --> C2[Tests d'intégration]
    
    D --> D1[README mis à jour]
    D --> D2[API documentée]
    
    E --> E1[Déployé en staging]
    E --> E2[Validé par PO]

Workflow de la User Story

#

    sequenceDiagram
    participant PO as Product Owner
    participant Dev as Développeur
    participant QA as Quality Assurance
    participant PM as Project Manager
    
    PO->>PM: Rédige la User Story
    PM->>Dev: Assigne la tâche
    Dev->>Dev: Développe la fonctionnalité
    Dev->>QA: Demande validation
    QA->>QA: Teste les scénarios
    
    alt Tests OK
        QA->>PO: Demande validation métier
        PO->>PM: Valide et marque "Done"
    else Tests KO
        QA->>Dev: Retour avec détails
        Dev->>Dev: Corrections
    end

Google Sheets Avancé pour la Gestion de Projet

#

Structure d’un Backlog dans Google Sheets

#

Onglet “Params”

#

Créer un onglet pour définir les valeurs de référence :

Renommer l’onglet :

1. Double-clic sur “Feuille 1”
2. Renommer en “Params”

Créer des plages nommées :

Définir les valeurs DoD et DoR :

Colonne A : Types de DoD

• Code développé
• Tests unitaires écrits
• Documentation mise à jour
• Code review effectuée
• Déployé en test

Colonne B : Types de DoR

• User Story rédigée
• Critères d’acceptation définis
• Complexité estimée
• Dépendances identifiées
• Maquettes disponibles

Nommer une plage de cellules :

1. Sélectionner les cellules A2:A6
2. Menu “Données” > “Plages nommées”
3. Nommer la plage “DoD”
4. Répéter pour DoR (B2:B6)

Onglet “Backlog”

#

Structure du backlog :

Configurer la validation des données :

1. Sélectionner la colonne “DoR”
2. Menu “Données” > “Validation des données”
3. Critères : “Liste d’une plage”
4. Plage : “DoD” (la plage nommée créée précédemment)
5. Répéter pour la colonne “DoD”

Formules Google Sheets Utiles

#

Configuration Préalable : Fonctions en Anglais

#

Pour utiliser les noms de fonctions en anglais uniquement :

1. Menu “Fichier” > “Paramètres”
2. Section “Calcul”
3. Cocher “Toujours utiliser le nom des fonctions en anglais”

Formules de Base

#

Compter le nombre de User Stories :

=COUNTA(A2:A50)

Cette formule compte toutes les cellules non vides de A2 à A50.

Somme de la complexité totale :

=SUM(C2:C50)

Complexité moyenne :

=AVERAGE(C2:C50)

Nombre de US terminées :

=COUNTIF(F2:F50, "Terminé")

Formules Avancées

#

Calcul du pourcentage de complétion :

=COUNTIF(F2:F50, "Terminé") / COUNTA(A2:A50) * 100

Filtre conditionnel (US en cours d’Alice) :

=FILTER(A2:G50, G2:G50="Alice", F2:F50="En cours")

Complexité totale par développeur :

=SUMIF(G2:G50, "Alice", C2:C50)

Références Absolues avec F4

#

Lors de la saisie d’une formule, appuyer sur F4 pour basculer entre :

• A1 : Référence relative (change lors de la copie)
• $A$1 : Référence absolue (ne change jamais)
• $A1 : Colonne absolue, ligne relative
• A$1 : Colonne relative, ligne absolue

Exemple d’utilisation :

=C2 * $H$1

Si H1 contient le taux horaire, cette formule calcule le coût d’une tâche en gardant toujours la référence à H1.

Tableau de Bord Visuel

#

Créer un tableau de bord pour suivre l’avancement :

Graphique en secteurs (Statuts) :

1. Sélectionner les colonnes “Statut” et “ID”
2. Menu “Insertion” > “Graphique”
3. Type : Graphique en secteurs
4. Personnaliser les couleurs

Graphique en barres (Complexité par développeur) :

Ces valeurs viennent des formules Excel :

• =SUMIF(G:G, “Alice”, C:C)
• =SUMIF(G:G, “Bob”, C:C)
• =SUMIF(G:G, “Charlie”, C:C)

Automatisation avec Mise en Forme Conditionnelle

Colorer les US selon leur statut :

Sélectionner la colonne “Statut”

Menu “Format” > “Mise en forme conditionnelle”

• Règle 1 : Si “Terminé” → Vert
• Règle 2 : Si “En cours” → Orange
• Règle 3 : Si “À faire” → Gris

Alerte sur complexité élevée :

Sélectionner la colonne “Complexité”

Menu “Format” > “Mise en forme conditionnelle”

Règle : Si valeur > 8 → Rouge

Google Apps Script pour l’Automatisation

#

Introduction à Google Apps Script

#

Google Apps Script est un langage de script basé sur JavaScript qui permet d’automatiser Google Workspace.

Accès à l’éditeur :

Dans Google Sheets : Menu “Extensions” > “Apps Script”

Un nouvel onglet s’ouvre avec l’éditeur de code

Structure d’un Projet Apps Script

#

// Code.gs - Fichier principal

/**
 * Fonction exécutée au chargement du document
 */
function onOpen() {
  const ui = SpreadsheetApp.getUi();
  ui.createMenu('Mon Menu')
    .addItem('Générer Rapport', 'generateReport')
    .addItem('Exporter en PDF', 'exportToPDF')
    .addToUi();
}

/**
 * Génère un rapport des User Stories
 */
function generateReport() {
  const sheet = SpreadsheetApp.getActiveSheet();
  const data = sheet.getDataRange().getValues();
  
  // Traitement des données
  Logger.log('Rapport généré');
}

Excercices

#

Exemple 1 : Calcul Automatique de la Vélocité

#

/**
 * Calcule la vélocité de l'équipe (points terminés / sprint)
 */
function calculateVelocity() {
  const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('Backlog');
  const data = sheet.getDataRange().getValues();
  
  let totalComplexity = 0;
  let completedStories = 0;
  
  // Parcourir les lignes (en ignorant l'en-tête)
  for (let i = 1; i < data.length; i++) {
    const status = data[i][5]; // Colonne "Statut"
    const complexity = data[i][2]; // Colonne "Complexité"
    
    if (status === "Terminé" && complexity) {
      totalComplexity += parseInt(complexity);
      completedStories++;
    }
  }
  
  // Afficher le résultat
  const ui = SpreadsheetApp.getUi();
  ui.alert(
    'Vélocité de l\'équipe', 
    `Stories terminées : ${completedStories}\nComplexité totale : ${totalComplexity}`,
    ui.ButtonSet.OK
  );
  
  return { completedStories, totalComplexity };
}

Exemple 2 : Export Automatique en PDF

#

/**
 * Exporte le backlog en PDF et l'envoie par email
 */
function exportBacklogToPDF() {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const sheet = ss.getSheetByName('Backlog');
  
  // Convertir la feuille en PDF
  const url = ss.getUrl().replace(/edit/, 'export?format=pdf&gid=' + sheet.getSheetId());
  
  const options = {
    headers: {
      'Authorization': 'Bearer ' + ScriptApp.getOAuthToken()
    }
  };
  
  const response = UrlFetchApp.fetch(url, options);
  const blob = response.getBlob().setName('Backlog_' + new Date().toISOString().split('T')[0] + '.pdf');
  
  // Envoyer par email
  GmailApp.sendEmail(
    'manager@example.com',
    'Backlog Export',
    'Veuillez trouver ci-joint l\'export du backlog.',
    {
      attachments: [blob]
    }
  );
  
  SpreadsheetApp.getUi().alert('PDF exporté et envoyé par email !');
}

Exemple 3 : Notification Automatique

#

/**
 * Envoie une notification quand une US est assignée
 */
function notifyOnAssignment() {
  const sheet = SpreadsheetApp.getActiveSheet();
  const range = sheet.getActiveRange();
  
  // Vérifier si la modification concerne la colonne "Assigné à"
  if (range.getColumn() === 7) { // Colonne G
    const assignedTo = range.getValue();
    const row = range.getRow();
    const usId = sheet.getRange(row, 1).getValue(); // Colonne A
    const usTitle = sheet.getRange(row, 2).getValue(); // Colonne B
    
    if (assignedTo) {
      // Récupérer l'email du développeur (à adapter)
      const email = getEmailByName(assignedTo);
      
      if (email) {
        GmailApp.sendEmail(
          email,
          `Nouvelle User Story : ${usId}`,
          `Bonjour ${assignedTo},\n\nLa User Story suivante vous a été assignée :\n\n${usId} : ${usTitle}\n\nBon développement !`
        );
      }
    }
  }
}

/**
 * Helper : Récupère l'email d'un développeur par son nom
 */
function getEmailByName(name) {
  const teamSheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('Team');
  const data = teamSheet.getDataRange().getValues();
  
  for (let i = 1; i < data.length; i++) {
    if (data[i][0] === name) {
      return data[i][1]; // Email en colonne B
    }
  }
  
  return null;
}

Exemple 4 : Mise à Jour Automatique des Dates

#

/**
 * Ajoute automatiquement la date de complétion
 */
function onEdit(e) {
  const sheet = e.source.getActiveSheet();
  const range = e.range;
  
  // Si la colonne "Statut" passe à "Terminé"
  if (range.getColumn() === 6 && range.getValue() === "Terminé") {
    const row = range.getRow();
    const dateColumn = 8; // Colonne H : "Date de fin"
    
    sheet.getRange(row, dateColumn).setValue(new Date());
  }
}

Déploiement d’un Script

#

Étapes pour déployer

#

Dans l’éditeur Apps Script : cliquer sur “Déployer” > “Nouveau déploiement” Type : “Module complémentaire” Description : “Automatisation Backlog” Déployer

Exécution manuelle

#

• Sélectionner la fonction dans la liste déroulante
• Cliquer sur “Exécuter”
• Autoriser les permissions la première fois

Déclencheurs automatiques

#

• Horloge (icône) dans la barre latérale
• “+ Ajouter un déclencheur”
• Fonction : calculateVelocity
• Source de l’événement : “Basé sur le temps”
• Type : “Déclencheur horaire”
• Intervalle : “Toutes les semaines”

Bonnes Pratiques

#

Documentation

#

Règle des 5W + 1H

#

Toujours documenter selon cette structure :

• Who (Qui) : Qui a créé/modifié ?
• What (Quoi) : Quelle fonctionnalité ?
• When (Quand) : Quand a-t-elle été développée ?
• Where (Où) : Où se trouve le code ?
• Why (Pourquoi) : Pourquoi cette implémentation ?
• How (Comment) : Comment l’utiliser ?

Versionner la Documentation

#

Dans Google Sheets :

• Menu “Fichier” > “Historique des versions”
• “Nommer la version actuelle”

Exemple : “v1.0 - Sprint 3 - Ajout US-256 à US-280”

Maintenir à Jour

#

Créer un rappel automatique :

/**
 * Envoie un rappel hebdomadaire pour mettre à jour la doc
 */
function sendDocumentationReminder() {
  const recipients = [
    'dev1@example.com',
    'dev2@example.com'
  ];
  
  recipients.forEach(email => {
    GmailApp.sendEmail(
      email,
      'Rappel : Mise à jour de la documentation',
      'N\'oubliez pas de mettre à jour la documentation du backlog cette semaine !'
    );
  });
}

Déclencheur : Tous les lundis à 9h

Collaboration

#

Partage de Documents

#

Niveaux de permission :

• Lecteur : Peut uniquement consulter
• Commentateur : Peut ajouter des commentaires
• Éditeur : Peut modifier le contenu

Commentaires et Suggestions

#

Utiliser les commentaires pour :

• Demander des clarifications sur une US
• Proposer des améliorations
• Signaler des problèmes

Raccourci : Ctrl + Alt + M (Windows) ou Cmd + Option + M (Mac)

Notifications

#

Configurer les notifications :

1. Fichier > “Paramètres de notification”
2. Choisir “M’envoyer une notification lorsque… Des modifications sont apportées”
3. Fréquence : “Au fur et à mesure”

Performance

#

Optimisation des Formules

#

Éviter :

=COUNTIF(F2:F1000, "Terminé") / COUNTA(A2:A1000)

Préférer (avec plages nommées) :

=COUNTIF(Status, "Terminé") / COUNTA(UserStories)

Limiter les scripts lourds

#

Pour les traitements volumineux :

function processLargeData() {
  const sheet = SpreadsheetApp.getActiveSheet();
  
  // Récupérer toutes les données en une seule fois
  const data = sheet.getDataRange().getValues();
  
  // Traiter en mémoire (rapide)
  const results = data.map(row => {
    // Traitement
    return processedRow;
  });
  
  // Écrire les résultats en une seule fois
  sheet.getRange(1, 1, results.length, results[0].length).setValues(results);
}

Conclusion

#

Récapitulatif

#

La documentation et Google Workspace offrent une synergie puissante pour :

Workflow Complet

#

    graph TD
    A[User Story] --> B[Google Docs]
    B --> C[Validation]
    C --> D[Google Sheets Backlog]
    D --> E[Apps Script]
    E --> F[Notifications]
    E --> G[Rapports]
    E --> H[Export PDF]
    D --> I[Développement]
    I --> J[Mise à jour DoD]
    J --> K[Documentation finale]

Les clés du succès

#

• Documenter dès le début (pas après)
• Poser les bonnes questions (Qui ? Quoi ? Pourquoi ?)
• Utiliser les bons outils (Google Workspace)
• Automatiser les tâches répétitives (Apps Script)
• Maintenir à jour régulièrement
• Collaborer activement