Ora che Genomica di JMP v4.1 è andato in produzione, ho trovato un po 'di tempo per recuperare la mia lettura. Mentre stavo esaminando un recente numero di Atti della National Academy of Sciences (USA) Sono rimasto colpito dal fatto che il limite tradizionale di 5 pagine è stato scartato e che articoli di 6 o più pagine sono diventati comuni. Le carte sono cresciute mentre gli investigatori cercano di mettere quante più informazioni possibile in sempre più spazio. Anche gli autori di Scienza rapporti, che sono stati tradizionalmente limitati a 2500 parole, aggirare i limiti della pagina includendo regolarmente collegamenti a Supporto dei materiali online , siti Web che contengono grandi quantità di dati e descrizioni aggiuntivi. Tutte queste informazioni tendono a sopraffare il lettore.
Forse sto solo mostrando di nuovo la mia età, ma mi mancano i giorni in cui si era limitati a un numero stabilito di parole o pagine rigorosamente applicate e non c'erano Materiali online supplementari . Gli autori dovevano assicurarsi che tutti i fatti e le figure di supporto necessari per raccontare una buona storia fossero inclusi nell'articolo. Questi requisiti obbligavano gli autori a considerare attentamente quali dati erano i più importanti e ad usare il linguaggio più conciso possibile. I buoni documenti erano nitidissimi e ti dicevano solo quello che dovevi sapere. Sono stati un piacere leggere.
"Solo i fatti, signora ..."
Sul vecchio rete radiante Serie TV (sto sicuramente mostrando la mia età qui!), Joe Friday ha usato queste parole per tagliare tutto il fluff e arrivare all'essenziale. Seguiamo la stessa filosofia quando scriviamo la documentazione per JMP Genomics. Abbiamo diviso il Guida dell'utente di JMP Genomics , per tema, in nove diversi volumi. Descriviamo ogni processo nel suo stesso capitolo. Vi diciamo cosa fa il processo e cosa avete bisogno per eseguirlo. Mostriamo quindi un esempio illustrativo e ti diciamo come interpretare i risultati.
Ogni capitolo è strutturato nello stesso modo; una volta che hai imparato come funziona per un processo, sai come funziona per ogni processo.
Un mio collega, che documenta un diverso pacchetto software, mi ha recentemente detto che la documentazione di Genomics di JMP era piuttosto semplice. Piuttosto che essere insultato, ho preso il suo commento come la più alta forma di lode. La documentazione del software non dovrebbe contenere un sacco di pelucchi. Invece, dovrebbe solo dirti quello che devi sapere in un formato facilmente accessibile e quindi dovrebbe toglierti di mezzo.
Il Guida dell'utente di JMP Genomics è progettato per fare proprio questo.
