La documentazione del software è solo un insieme di articoli. Ma anche loro possono farti impazzire. Innanzitutto, passi molto tempo a cercare le istruzioni necessarie. Allora capisci il testo oscuro. Fai come scritto, ma il problema non è risolto. Cerchi un altro articolo, ti innervosisci... Un'ora dopo molli tutto e te ne vai. Ecco come funziona la cattiva documentazione. Cosa lo rende così e come risolverlo: leggi sotto il taglio.
C'erano molte carenze nella nostra vecchia documentazione. Lo stiamo rielaborando da quasi un anno ormai in modo che lo scenario sopra descritto non influisca sui nostri clienti. Aspetto, и .
Problema 1: articoli poco chiari e scritti male
Se la documentazione è impossibile da comprendere, che senso ha? Ma nessuno scrive apposta articoli incomprensibili. Accadono quando l'autore non pensa al pubblico e allo scopo, versa acqua e non controlla la presenza di errori nel testo.
- pubblico. Prima di scrivere un articolo bisogna pensare al livello di preparazione del lettore. È logico che in un articolo per principianti non si debbano saltare i passaggi fondamentali e lasciare i termini tecnici senza spiegazione, ma in un articolo su una funzionalità rara di cui solo i professionisti hanno bisogno, si dovrebbe spiegare il significato della parola PHP.
- bersaglio. Un'altra cosa a cui pensare in anticipo. L'autore deve stabilire un obiettivo chiaro, determinare l'effetto utile dell'articolo e decidere cosa farà il lettore dopo averlo letto. Se ciò non viene fatto, ti ritroverai con una descrizione fine a se stessa.
- Acqua e insetti. Ci sono molte informazioni e burocrazia non necessarie, errori ed errori di battitura interferiscono con la percezione. Anche se il lettore non è un nazista della grammatica, la disattenzione nel testo può spegnerlo.
Considera i suggerimenti sopra riportati e gli articoli diventeranno più chiari, garantito. Per renderlo ancora migliore, usa il nostro .
Problema 2. Gli articoli non rispondono a tutte le domande
È un male quando la documentazione non tiene il passo con lo sviluppo, non risponde a domande reali e gli errori in essa contenuti non vengono corretti per anni. Si tratta di problemi non tanto dell'autore, ma dell'organizzazione dei processi all'interno dell'azienda.
La documentazione non tiene il passo con lo sviluppo
La funzionalità è già in fase di rilascio, il marketing prevede di coprirla, ma poi si scopre che il nuovo articolo o traduzione non è ancora nella documentazione. Per questo motivo abbiamo addirittura dovuto posticipare l'uscita. Puoi chiedere a tutti di affidare le attività agli scrittori tecnici in tempo quanto vuoi, ma non funzionerà. Se il processo non è automatizzato, la situazione si ripeterà.
Abbiamo apportato modifiche a YouTrack. Il compito di scrivere un articolo su una nuova funzionalità spetta al redattore tecnico nel momento stesso in cui la funzionalità inizia a essere testata. Quindi il marketing lo apprende per prepararsi alla promozione. Le notifiche arrivano anche al messenger aziendale Mattermost, quindi è semplicemente impossibile perdere le notizie degli sviluppatori.
La documentazione non riflette le richieste degli utenti
Siamo abituati a lavorare così: è uscita una funzionalità, ne abbiamo parlato. Abbiamo descritto come accenderlo, spegnerlo ed effettuare regolazioni fini. Ma cosa succede se un cliente utilizza il nostro software in un modo che non ci aspettiamo? Oppure presenta errori a cui non abbiamo pensato?
Per garantire che la documentazione sia quanto più completa possibile, consigliamo di analizzare le richieste di supporto, le domande sui forum tematici e le query nei motori di ricerca. Gli argomenti più popolari verranno trasferiti ai redattori tecnici in modo che possano integrare gli articoli esistenti o scriverne di nuovi.
La documentazione non viene migliorata
È difficile farlo perfettamente subito; ci saranno ancora degli errori. Puoi sperare nel feedback dei clienti, ma è improbabile che segnalino ogni errore di battitura, inesattezza, articolo incomprensibile o non trovato. Oltre ai clienti, i dipendenti leggono la documentazione, il che significa che vedono gli stessi errori. Questo può essere usato! Devi solo creare le condizioni in cui sarà facile segnalare un problema.
Abbiamo un gruppo sul portale interno in cui i dipendenti lasciano commenti, suggerimenti e idee sulla documentazione. Il supporto necessita di un articolo, ma non esiste? Il tester ha notato l'imprecisione? Il partner si è lamentato degli errori con i responsabili dello sviluppo? Tutti in questo gruppo! Gli autori tecnici risolvono subito alcune cose, trasferiscono alcune cose su YouTrack e concedono ad altri un po' di tempo per pensarci. Per evitare che l'argomento si spenga, di tanto in tanto vi ricordiamo l'esistenza del gruppo e l'importanza del feedback.
Problema 3. Ci vuole molto tempo per trovare l'articolo giusto.
Un articolo che non può essere trovato non è migliore di un articolo che non può essere trovato. Il motto di una buona documentazione dovrebbe essere “Facile da cercare, facile da trovare”. Come raggiungere questo obiettivo?
Organizzare la struttura e determinare il principio per la scelta degli argomenti. La struttura dovrebbe essere il più trasparente possibile in modo che il lettore non pensi: “Dove posso trovare questo articolo?” Per riassumere, ci sono due approcci: dall'interfaccia e dai compiti.
- Dall'interfaccia. Il contenuto duplica le sezioni del pannello. Questo era il caso della vecchia documentazione del sistema ISP.
- Dai compiti. I titoli degli articoli e delle sezioni riflettono i compiti degli utenti; I titoli contengono quasi sempre verbi e risposte alla domanda “come fare”. Ora stiamo passando a questo formato.
Qualunque sia l'approccio scelto, assicurati che l'argomento sia pertinente a ciò che gli utenti stanno cercando e sia trattato in modo da rispondere specificamente alla domanda dell'utente.
Imposta una ricerca centralizzata. In un mondo ideale, la ricerca dovrebbe funzionare anche in caso di errori di ortografia o di lingua. La nostra ricerca in Confluence finora non può soddisfarci. Se disponi di molti prodotti e la documentazione è generale, adatta la ricerca alla pagina in cui si trova l'utente. Nel nostro caso, la ricerca nella pagina principale funziona per tutti i prodotti e, se ti trovi già in una sezione specifica, solo per gli articoli in essa contenuti.
Aggiungi contenuto e breadcrumb. Va bene quando ogni pagina ha un menu e breadcrumb: il percorso dell'utente alla pagina corrente con la possibilità di tornare a qualsiasi livello. Nella vecchia documentazione del sistema ISP, dovevi uscire dall'articolo per accedere al contenuto. Era scomodo, quindi l'abbiamo risolto in quello nuovo.
Inserisci i link nel prodotto. Se le persone continuano a fornire supporto con la stessa domanda, ha senso aggiungere un suggerimento con la relativa soluzione all'interfaccia. Se disponi di dati o informazioni su quando un utente riscontra un problema, puoi anche avvisarlo con una mailing list. Mostra loro preoccupazione e alleggerisci il peso del supporto.
A destra nella finestra pop-up c'è un collegamento a un articolo sulla configurazione di DNSSEC nella sezione di gestione del dominio di ISPmanager
Impostare riferimenti incrociati all'interno della documentazione. Gli articoli correlati tra loro dovrebbero essere "collegati". Se gli articoli sono sequenziali, assicurati di aggiungere le frecce avanti e indietro alla fine di ogni testo.
Molto probabilmente, una persona andrà prima a cercare una risposta alla sua domanda non a te, ma a un motore di ricerca. È un peccato che per motivi tecnici non siano presenti collegamenti alla documentazione. Quindi prenditi cura dell’ottimizzazione dei motori di ricerca.
Problema 4. Il layout obsoleto interferisce con la percezione
Oltre ai testi scadenti, la documentazione può essere rovinata dalla progettazione. Le persone sono abituate a leggere materiali ben scritti. Blog, social network, media: tutti i contenuti sono presentati non solo belli, ma anche facili da leggere e piacevoli alla vista. Pertanto, puoi facilmente comprendere il dolore di una persona che vede il testo come nello screenshot qui sotto.
Ci sono così tanti screenshot e punti salienti in questo articolo che non aiutano, ma interferiscono solo con la percezione (l'immagine è cliccabile)
Non dovresti leggere a lungo la documentazione con una serie di effetti, ma devi tenere in considerazione le regole di base.
Disposizione. Determina la larghezza, il carattere, la dimensione, i titoli e il riempimento del corpo del testo. Assumi un designer e, per accettare il lavoro o farlo da solo, leggi il libro di Artyom Gorbunov "Tipografia e layout". Presenta solo una vista del layout, ma è abbastanza sufficiente.
selezione. Determina cosa deve essere enfatizzato nel testo. In genere si tratta di un percorso nell'interfaccia, pulsanti, inserti di codice, file di configurazione, blocchi "Nota". Determinare quali saranno le allocazioni di questi elementi e registrarle nei regolamenti. Tieni presente che minore è la scarica, meglio è. Quando ce ne sono molti, il testo è rumoroso. Anche le virgolette creano rumore se vengono utilizzate troppo spesso.
Screenshots. Concordare con il team in quali casi sono necessari gli screenshot. Non è assolutamente necessario illustrare ogni passaggio. Un gran numero di screenshot, incl. pulsanti separati, interferiscono con la percezione, rovinano il layout. Determina la dimensione, nonché il formato delle evidenziazioni e delle firme sugli screenshot e registrali nei regolamenti. Ricorda che le illustrazioni dovrebbero sempre corrispondere a ciò che è scritto ed essere pertinenti. Anche in questo caso, se il prodotto viene aggiornato regolarmente, sarà difficile tenere traccia di tutti.
Lunghezza del testo. Evita articoli troppo lunghi. Suddividili in parti e, se ciò non è possibile, aggiungi contenuto con collegamenti di ancoraggio all'inizio dell'articolo. Un modo semplice per rendere visivamente più breve un articolo è nascondere i dettagli tecnici necessari a una ristretta cerchia di lettori sotto uno spoiler.
formati. Combina diversi formati nei tuoi articoli: testo, video e immagini. Ciò migliorerà la percezione.
Non cercare di nascondere i problemi con un bel layout. Onestamente, noi stessi speravamo che il "wrapper" salvasse la documentazione obsoleta - non ha funzionato. I testi contenevano così tanto rumore visivo e dettagli inutili che i regolamenti e il nuovo design erano impotenti.
Gran parte di quanto sopra sarà determinato dalla piattaforma utilizzata per la documentazione. Ad esempio, abbiamo Confluenza. Anch'io ho dovuto armeggiare con lui. Se interessato, leggi la storia del nostro sviluppatore web: .
Da dove iniziare a migliorare e come sopravvivere
Se la tua documentazione è vasta quanto quella di ISPsystem e non sai da dove cominciare, inizia dai problemi più grandi. I clienti non capiscono il documento: migliorano i testi, stabiliscono regolamenti, formano gli scrittori. La documentazione non è aggiornata: prenditi cura dei processi interni. Inizia con gli articoli più popolari sui prodotti più popolari: chiedi supporto, guarda l'analisi del sito e le query nei motori di ricerca.
Diciamo subito: non sarà facile. Ed è improbabile che funzioni rapidamente. A meno che tu non abbia appena iniziato e faccia subito la cosa giusta. Una cosa che sappiamo per certo è che col tempo migliorerà. Ma il processo non finirà mai :-).
Fonte: habr.com