Limitare la documentazione alle informazioni rilevanti per le decisioni
Una documentazione utile spiega decisioni, operazioni e limitazioni. I dettagli ricavabili vengono collegati o generati anziché essere mantenuti ridondanti.
Per gli operatori di siti web e i CTO, "focalizzare la documentazione sulle conoscenze rilevanti" può essere valutato utilizzando tre esempi concreti: "Conoscenza non derivabile", "Decisioni concrete" e "Codice in prosa".
Pubblicato: 3 minuti di lettura · Autore: Sebastian Geier
Quali conoscenze dovrebbe includere la documentazione tecnica e quali no?
Le informazioni preziose includono lo scopo, i limiti del sistema, le ipotesi non ovvie, le alternative scartate, la proprietà dei dati, i processi operativi e i criteri decisionali. Le configurazioni e i test eseguibili dovrebbero rimanere nel repository ove possibile; i documenti dovrebbero avere un pubblico di destinazione, un responsabile e un trigger di test anziché una generica promessa di aggiornamento.
Decisione concreta
Raccogli le decisioni e le attività operative per le quali il personale competente deve attualmente ricercare il contesto al di fuori del sistema.
Sposta i dettagli derivabili automaticamente nel codice, nei test o nell'inventario e condensa le informazioni rimanenti in modo orientato al gruppo target.
Imposta il responsabile e il trigger di audit per ciascun documento e archivia o rimuovi le pagine non pertinenti alla decisione corrente.
Trigger gestibile
Percentuale di documenti utilizzati, inclusi il pubblico di destinazione, la decisione specifica, il responsabile e l'evento per il prossimo audit.
Tempo di risposta alle domande operative e architetturali, nonché numero di copie manuali in conflitto dei dettagli eseguibili.
Codice in prosa
Codice in prosa Parametri, endpoint e processi vengono duplicati manualmente e risultano in contraddizione con il sistema dopo ogni modifica all'implementazione.
Decisione senza contesto Un risultato viene documentato, ma mancano le motivazioni e le alternative scartate, e la stessa discussione si ripresenta in seguito.
Wiki senza proprietario Molte pagine non riportano la data di creazione o di revisione, rendendo difficile reperire informazioni importanti e aggiornate tra le versioni precedenti.
Conoscenza non derivabile
Conoscenza non derivabile Il contenuto spiega il contesto, l'intento o le limitazioni che non sono immediatamente evidenti dal codice, dallo schema e dall'inventario automatico correnti.
Decisione concreta – Un ruolo denominato utilizza le conoscenze per operazioni, modifiche, escalation, assunzione del rischio o selezione dell'architettura.
Trigger gestibile – La proprietà e gli eventi come rilasci, modifiche del fornitore o incidenti determinano quando il contenuto deve essere revisionato.
Verifica incrociata: "Codice in prosa"
Una wiki copia tutte le variabili d'ambiente ed è obsoleta. Le variabili vengono documentate automaticamente dallo schema; ciò che resta da capire è perché esistono due limiti di sicurezza insoliti, chi è autorizzato a modificarli e quale test convalida la decisione.
Come "Concentrare la documentazione sulle conoscenze rilevanti" si relaziona alle decisioni correlate
Da "Concentrare la documentazione sulle conoscenze rilevanti" Notifica tempestiva della disattivazione di API, plugin e servizi. un'importante domanda di approfondimento: come si riconosce e si gestisce tempestivamente la dismissione di API, plugin e servizi?
Chi desidera approfondire "Concentrare la documentazione sulle conoscenze rilevanti" dal punto di vista del cluster "Strategia di piattaforma e Build-vs-Buy" troverà ulteriori informazioni in: Mantenere un file decisionale solido per i sistemi digitali la classificazione appropriata.
Se desideri mettere in pratica il principio di "focalizzare la documentazione sulle conoscenze rilevanti", puoi trovare maggiori informazioni su... Sistemi web robusti attingere alle risorse esistenti. L'attenzione si concentra su "accesso, proprietà e conoscenza operativa" e "conoscenza non derivabile".
Conclusione: Concentrare la documentazione sulla conoscenza rilevante
Una buona documentazione aggiunge contesto e capacità decisionali al sistema. Minore è la duplicazione di informazioni eseguibili, più facile sarà mantenere aggiornata la conoscenza realmente non derivabile.
Fonti e ulteriori informazioni
Queste fonti primarie sono cruciali per il comportamento della piattaforma, la terminologia e i limiti di audit quando si "focalizza la documentazione sulla conoscenza rilevante".
14. Gestire un servizio affidabile – Manuale di servizio GOV. UKStandard ufficiale per il team operativo, il monitoraggio, il supporto, la sicurezza, il ripristino e la responsabilità continua del servizio.
Principi di governance per un'erogazione agile dei servizi – Manuale di servizio GOV. UKPrincipi di governance ufficiali per una chiara autorità decisionale, responsabilità delegata, trasparenza e risultati verificabili.
Tesi chiave
La documentazione rappresenta ciò che un team competente non può ricavare dal codice o dal sistema e di cui ha bisogno per prendere decisioni o per operare. La proprietà e i programmi di audit la mantengono aggiornata.
Cosa non riguarda
La documentazione tecnica non deve ripetere ogni percorso del codice o descrivere ogni interfaccia; entrambe diventano obsolete più velocemente di quanto un team competente possa utilizzarle.
Di cosa si tratta
Documentare ciò che non è derivabile in modo affidabile dal codice e dalle informazioni di sistema, ma è necessario per il funzionamento, la modifica, la valutazione del rischio e le decisioni precedenti.
Manutenzione, dipendenze e debito tecnico.
Documentare in modo trasparente i problemi tecnici preesistenti durante il passaggio di consegne ai clienti.
"Concentrare la documentazione sulle conoscenze rilevanti" include, come fase di revisione separata, la domanda: Come vengono documentati in modo trasparente i problemi tecnici preesistenti durante il passaggio di consegne al cliente?
Manutenzione, dipendenze e debito tecnico.
Calcolare l'impegno di manutenzione come parte della decisione architetturale.
Integra "Concentrare la documentazione sulle conoscenze rilevanti" con una decisione separata: Come viene integrato l'impegno di manutenzione futuro in una decisione architetturale?
Panoramica degli Insight
Tutti gli Insight di VELUNO in sintesi
Ulteriori analisi sui sistemi web, la visibilità digitale e modelli di lavoro robusti.
Decisione concreta: prossima decisione affidabile.
Una pagina wiki utilizzata frequentemente dovrebbe essere controllata frase per frase per verificarne la derivabilità del codice e i processi decisionali specifici. I duplicati vengono spostati nel codice sorgente e al contesto viene assegnato un responsabile e dei trigger per la verifica.