Documenta il diavolo su tutto.
Recentemente c'è stato un thread su Slashdot sull'avvio della documentazione, che mi ha ispirato a scrivere i miei pensieri sulla documentazione.
I miei punti chiave erano:
Principio n. 1: non viene mai fatto
La documentazione è uno sforzo continuo che rimarrà sempre indietro rispetto a ciò che è in produzione. Le modifiche vengono apportate ad hoc, le cose vengono spostate o interrotte o messe in servizio a caso. La documentazione non raggiungerà mai.
Devi vendere le persone che pagano le bollette sul valore del tempo speso (e quindi del denaro) per mantenere aggiornata la documentazione in corso. Spesso quelle conversazioni vanno così: "ricordi quando ho dovuto spendere $ TIME per capire come $ THING è stato rotto? Beh, quando ho finito, c'era questa nota tecnica che dettagliava $ THING, in modo che il prossimo ragazzo a venire non lo farà devo capire tutto ".
Devi farlo, anche se non finirai mai.
Principio n. 2: l'unica cosa peggiore di nessuna documentazione è la documentazione sbagliata
Questo è più un vero truismo che un principio. La documentazione può cullarti nel falso senso che qualcosa è in uno stato noto e che se qualcosa va storto puoi quindi iniziare a correggerlo.
È importante riconoscere questo problema.
Principio n. 3: stai scrivendo documentazione per il tuo successore
Le probabilità sono il 95% di qualsiasi cosa tu faccia documenti a cui non dovrai mai più fare riferimento. La documentazione è una raccolta di saggezza per il futuro, non per te. Quindi devi presumere che il tuo pubblico sappia poco o niente sui dettagli di come le cose sono come sono.
E ci sarà un successore. Non ti conosco, ma non ho intenzione di essere in questi ambienti specifici per il resto della mia vita. Le opportunità vanno e vengono, e quando arrivano, a volte vai. Ma la vita continua dietro di te e più liscia puoi rendere migliore la vita per il tuo successore. Altrimenti potresti avere una collezione di ex clienti che dicono tranquillamente cose poco lusinghiere su di te. Mi piace dire che sono gli stessi 50 ragazzi che lavorano ovunque nell'IT a Ottawa perché continui a incontrarti ovunque. Aiutare il tuo successore potrebbe aprirti le porte in futuro.
Ora, fino a un certo punto, c'è sempre un certo grado di "incolpare il ragazzo precedente" quando sorgono problemi. Questo fa parte del business. L'ho fatto da solo. Ma in diverse occasioni in cui avevo fatto esplodere il ragazzo precedente come una specie di idiota, ho imparato diversamente che aveva davvero recitato insieme e sapeva più di quello che stava succedendo in quel momento.
Principio n. 4: "Perché" è spesso più importante di "Come"
Quando guardiamo un sistema, la maggior parte di noi inizia a pensare come perché diavolo è così? Ci sono quasi sempre ragioni molto specifiche per le scelte di configurazione fatte. In queste circostanze, il "Perché" detta il "Come" e devi assicurarti che il lettore comprenda i problemi specifici che vengono risolti quando si esaminano i resti di fumo della tua soluzione.
Principio n. 5: deve essere facile o non lo farai
Ciò significa che devi essere molto consapevole dei tuoi strumenti e di quelli che useranno i tuoi strumenti.
Mantenere le cose aggiornate deve essere facile. Se devi fare qualsiasi tipo di sforzo, troverai delle scuse per evitare di farlo quando è fatto meglio, che è immediatamente dopo un cambiamento.
Se i tuoi strumenti non sono facili da usare per gli altri, non li useranno. Questo può essere particolarmente paralizzante in un ambiente di squadra, poiché più è grande la squadra, più è probabile che incontrerai un membro della squadra a cui non piace la tua scelta di strumenti.
Personalmente, mi piace un wiki per i documenti. Tuttavia, il problema è che una wiki non ti impone una struttura, quindi la struttura deve essere imposta dall'esterno. Questo porta sempre al conflitto da qualche parte poiché qualcun altro ha un'idea migliore / diversa.
In alcuni punti ho usato i documenti Word e Visio "pubblicati" in PDF, con il "più recente" PDF considerato autorevole. Questo è positivo in quanto hai una collezione che puoi consegnare al tuo datore di lavoro / successore. I PDF, se correttamente datati, possono fornire una cronologia di ciò che è accaduto, sebbene non sia facile da navigare. È un male perché non mi piacciono Word o Visio e sono stato costretto a ottenere una conoscenza di base di questi strumenti per comunicare efficacemente le idee.
Il mio attuale datore di lavoro sta giocando con l'idea dei documenti di Word in un portale Sharepoint. Dovremo solo vedere fino a che punto ci arriviamo