Quali sono i documenti software più interessanti che tu abbia mai visto?

Non posso davvero parlare per il più cool. Preferisco che la documentazione sia funzionale piuttosto che interessante.

Ma la documentazione più “leggibile” che ho letto ha le seguenti proprietà:

  • Breve ma completo . I documenti sono efficaci solo se le persone li leggono. Il problema con i documenti lunghi è che a volte ci vuole troppo tempo per ottenere alcuni punti chiave. Alcuni recensori tendono a leggere le prime pagine. Ho avuto questo progetto una volta che un grande documento di 20 con casi d’uso che descrivono uno scenario di flusso di lavoro. Abbiamo avuto un problema con il flusso e volevamo generalizzarlo. Ha iniziato a dare un senso solo dopo averlo riassunto in 5 diagrammi di stato con collaterali associati. A meno che il valore dell’affare non sia misurato da un sovrano.
  • Leggibile. Evita di usare un linguaggio inappropriato per il lettore di destinazione. Prova a usare la lingua più semplice possibile. Cercare di sembrare “sofisticato” non è l’obiettivo della documentazione software. Ho avuto un documento che ho letto una volta in cui lo scrittore stava cercando di utilizzare “parla avvocato” per scrivere il documento. Il documento è appena riuscito a distrarmi dall’ottenere il punto.
  • Pieno di belle immagini . I diagrammi comunicano meglio di lunghe righe e righe di testo dettagliate. È molto più semplice rivedere flussi e concetti in forma di diagramma. Naturalmente, usa il diagramma appropriato per descrivere la cosa appropriata. Una volta ho avuto un cliente che ha presentato un documento di oltre 10 pagine che descrive la transizione di attività in un sistema di informatica medica. Siamo tornati da lui per presentare la nostra comprensione delle transizioni di stato con un singolo diagramma. Fortunatamente, ha accettato che fosse una rappresentazione migliore e ha catturato bene le sue esigenze. Andando avanti abbiamo confermato la nostra comprensione con i disegni.
  • Aggiornato e preciso . La parte peggiore di non avere documentazione è avere documentazione errata. Questo crea un falso senso di sicurezza. Uno dei motivi principali per avere una documentazione errata non è tenerlo aggiornato. Una volta ho avuto un cliente che ha documentato la loro interazione con un particolare sistema bancario. Il documento ha insistito sull’uso di una determinata lunghezza della chiave. I nostri ingegneri hanno insistito sul fatto che non potrebbe essere il caso perché le regole normative richiedono il doppio della dimensione della chiave. Quindi il cliente fornisce i tasti di scelta rapida e abbiamo trascorso oltre 2 mesi a provare varie permutazioni per interfacciarsi con il sistema. Alla fine abbiamo avuto una svolta quando abbiamo fatto una procedura dettagliata per la creazione della chiave e abbiamo notato che il sistema ha generato sia una chiave lunga che una corta. Abbiamo chiesto la chiave lunga e l’abbiamo provata. Ha funzionato immediatamente. La documentazione obsoleta equivale a 2 mesi di sforzi sprecati.

Ho riscontrato quanto segue nella mia carriera. Ma non so se la leggibilità sia effettivamente migliorata. Tuttavia, non mi sono annoiato di meno leggendo i documenti.

  • Personaggi di Star Wars che definiscono le relazioni dell’oggetto come parte dei commenti. I nomi delle classi erano funzionali. I commenti avevano “Questa è la classe Luke che discende dalla classe Anakin”. In alcuni casi, Luke eredita i poteri jedi di Anakin o Anakin con istanze sia Jedi che Sith. Non sono sicuro se i fan delle guerre non star troveranno questo facile da leggere.
  • Una volta ho visto un documento che conteneva tutti i diagrammi . È stato facile affrontarlo ed è stato molto chiaro sul comportamento previsto.

Hai qualche esempio di buono?