Linee guida per una buona documentazione¶
Ogni gruppo dovrà scrivere una documentazione, per aggiornare tutti i gruppi sulle modifiche che avete fatto nelle riunioni settimanali. La cosa importante è scrivere una buona documentazione, seguendo determinati criteri che vi andremo ad indicare:
Ordine e organizzazione;
Precisione e chiarezza;
Feedback e aggiornabilità;
Andiamo a vederli in dettaglio.
Ordine e organizzazione¶
Il primo punto è molto banale, ma importantissimo per ordinare ed organizzare la nostra documentazione. Questo lo otteniamo grazie ad alcune regole di sintassi:
Dividere in paragrafi gli argomenti;
Utilizzare i titoli per specificare i paragrafi;
Utilizzare elenchi puntati per differenziare gli argomenti di cui discute il paragrafo;
La cosa fondamentale che deve avere una buona documentazione è quella di non creare confusione. Quando una qualsiasi persona entra per visionare la vostra documentazione, deve arrivare facilmente e velocemente a quello che sta cercando.
Di seguito un esempio di una documentazione ben ordinata e ben organizzata:
Come vedete abbiamo un titolo grande, che inquadra subito quello di cui sta parlando il paragrafo. Al di sotto troviamo anche un elenco puntato, per differenziare gli argomenti che discute quel pagarafo.
Precisione e chiarezza¶
Ovviamente la nostra documentazione deve avere chiarezza e precisione dal punto di vista grammaticale e sintattico. Questo lo otteniamo grazie alle regole base di una buona grammatica. Il buon utilizzo della grammatica, ovviamente, porterà ad avere una chiarezza nella creazione sintattica della documentazione. Dunque quando scriviamo una documentazione, bisogna stare attenti all’uso corretto di tempi verbali (di solito si tende ad utilizzare il presente), l’uso giusto delle virgole e dei punti per creare una metodologia di comprensione giusta e veloce al lettore.
Per precisione si intende che, quando si scrive la documentazione, bisogna andare dritti al punto, senza fare troppi giri di parole, poiché ciò desta distrazione e quindi una perdita di tempo.
Feedback e Aggiornabilità¶
Con feedback e aggiornabilità si intende: Se si modifica una parte di codice (ad esempio viene modificata una funzione del backend), il gruppo che ha effettuato tali modifiche ha la responsabilità di aggiornare la documentazione per non farla rimanere indietro rispetto al lavoro che si sta facendo, in modo tale da avere un documento sempre aggiornato e al passo con il lavoro che si fa.
Seguendo queste linee guida, avrete una documentazione efficace e ben organizzata. Buon lavoro.