La documentazione del software è semplicemente un insieme di articoli. Ma anche questi possono frustrare. Inizialmente cerchi a lungo l'istruzione giusta. Poi ti districhi in un testo poco chiaro. Fai come scritto, ma il problema non si risolve. Cerchi un altro articolo, ti innervosisci... Dopo un'ora ti arrendi e te ne vai. Così funziona una cattiva documentazione. Cosa la rende tale e come risolverlo — leggi di seguito.
Nella nostra vecchia documentazione c'erano molti difetti. Da quasi un anno la stiamo rielaborando, affinché lo scenario descritto sopra non riguardi i nostri clienti. Guarda, e .
Problema 1. Articoli poco chiari e scritti male
Se è impossibile orientarsi nella documentazione, qual è il suo senso? Ma nessuno scrive articoli poco chiari volutamente. Questi si creano quando l'autore non pensa al pubblico e agli obiettivi, scrive senza sostanza e non controlla il testo per errori.
- Pubblico. Prima di scrivere un articolo bisogna pensare al livello di preparazione del lettore. È logico che in un articolo per principianti non si devono saltare i passaggi di base e lasciare i termini tecnici senza spiegazioni, mentre in un articolo su una funzione rara, utile solo ai professionisti, non si deve spiegare il significato della parola PHP.
- Obiettivo. Un'altra cosa su cui è meglio riflettere in anticipo. L'autore deve stabilire un obiettivo chiaro, definire l'azione utile dell'articolo e decidere cosa farà il lettore dopo averlo letto. Se non lo si fa, avremo una descrizione fine a se stessa.
- Informazioni superflue ed errori. Troppe informazioni inutili e gergo burocratico, errori e refusi ostacolano la comprensione. Anche se il lettore non è un perfezionista della grammatica, la trascuratezza nel testo può allontanarlo.
Seguendo i consigli sopra, gli articoli diventeranno più chiari — garantito. Per fare ancora meglio, prendi in considerazione le nostre .
Problema 2. Gli articoli non rispondono a tutte le domande
È negativo quando la documentazione non tiene il passo con lo sviluppo, non risponde a domande reali e gli errori non vengono corretti per anni. Questi problemi riguardano più l'organizzazione dei processi all'interno dell'azienda che l'autore.
La documentazione non tiene il passo con lo sviluppo
La funzionalità è già in fase di rilascio, il marketing prevede di farne comunicazione, e si scopre che non c'è ancora nessun articolo o traduzione nella documentazione. A causa di ciò, abbiamo dovuto persino posticipare il rilascio. Possiamo chiedere a tutti di inviare la richiesta agli scrittori tecnici in tempo, ma non funzionerà. Se il processo non viene automatizzato, la situazione si ripeterà.
Abbiamo apportato modifiche a YouTrack. La richiesta di scrivere un articolo sulla nuova funzionalità viene assegnata allo scrittore tecnico non appena inizia il collaudo della funzione. Allo stesso tempo, ne viene informato il marketing per prepararsi alla promozione. Le notifiche arrivano anche nel messaggistico aziendale Mattermost, quindi è impossibile perdere notizie dagli sviluppatori.
La documentazione non rispecchia le richieste degli utenti
Siamo abituati a lavorare così: la funzionalità viene rilasciata, noi ne parliamo. Descriviamo come attivarla, disattivarla, fare impostazioni dettagliate. Ma cosa succede se il cliente utilizza il nostro software in modi che non avevamo previsto? O se si verificano errori a cui non abbiamo pensato?
Per rendere la documentazione il più completa possibile, consigliamo di analizzare le richieste di assistenza, le domande nei forum tematici, le ricerche nei motori di ricerca. I temi più popolari da passare agli scrittori tecnici affinché amplino gli articoli esistenti o ne scrivano di nuovi.
La documentazione non si evolve
È difficile ottenere un risultato perfetto fin da subito, ci saranno comunque errori. Possiamo sperare nel feedback dei clienti, ma è poco probabile che riferiscano ogni refuso, imprecisione, articolo poco chiaro o non trovato. Oltre ai clienti, la documentazione viene letta dai dipendenti, il che significa che possono notare gli stessi errori. Possiamo utilizzare questo! Bisogna solo creare condizioni che facilitino la segnalazione dei problemi.
Abbiamo un gruppo nel portale interno, dove i dipendenti possono lasciare osservazioni, suggerimenti e idee sulla documentazione. Il supporto ha bisogno di un articolo, ma non c'è? Un tester ha notato un'imprecisione? Un partner ha segnalato errori ai responsabili dello sviluppo? Tutto in questo gruppo! Gli scrittori tecnici correggono immediatamente alcune cose, spostano altre in YouTrack e alcune le prendono in considerazione. Per non lasciar cadere l'argomento, di tanto in tanto ricordiamo l'esistenza del gruppo e l'importanza del feedback.
Problema 3. L'articolo necessario richiede molto tempo per essere trovato
Un articolo che non si può trovare non è migliore di un articolo che non esiste. Il motto di una buona documentazione dovrebbe essere la frase "Facile da cercare, facile da trovare". Come raggiungerlo?
Ordinare la struttura e definire il principio di scelta dei temi. La struttura deve essere il più trasparente possibile, affinché il lettore non si chieda "Dove posso trovare questo articolo?". In sintesi, ci sono due approcci: dall'interfaccia e dalle attività.
- Dall'interfaccia. I contenuti duplicano le sezioni del pannello. Così era nella vecchia documentazione di ISPsystem.
- Dalle attività. I titoli degli articoli e delle sezioni rispecchiano le necessità degli utenti; nei titoli ci sono quasi sempre verbi e risposte alla domanda "come fare". Ora stiamo passando a questo formato.
Qualunque approccio scegliate, assicuratevi che il tema corrisponda alle richieste degli utenti e sia trattato in modo da risolvere esattamente la loro domanda.
Organizzare una ricerca centralizzata. In un mondo ideale la ricerca dovrebbe funzionare anche quando si fanno errori di battitura o si sbaglia lingua. La nostra ricerca in Confluence al momento non può soddisfare questa esigenza. Se avete molti prodotti e la documentazione è generale, adattate la ricerca alla pagina in cui si trova l'utente. Nel nostro caso la ricerca sulla home page funziona per tutti i prodotti, mentre se siete già in una sezione specifica, solo per gli articoli in essa.
Aggiungere un sommario e "briciole di pane". È utile avere un menu e delle briciole di pane in ogni pagina: il percorso dell'utente fino alla pagina corrente con la possibilità di tornare a qualsiasi livello. Nella vecchia documentazione di ISPsystem era necessario uscire dall'articolo per accedere al sommario. Era scomodo, quindi abbiamo corretto questa situazione nella nuova.
Posizionare i link nel prodotto. Se gli utenti si rivolgono ripetutamente al supporto con la stessa domanda, è sensato aggiungere un suggerimento con la soluzione nell'interfaccia. Se avete dati o comprendete in quale momento l'utente incontra un problema, potete anche avvisarlo tramite newsletter. In questo modo dimostrate attenzione e alleviate il carico del supporto.
A destra nella finestra pop-up il link all'articolo sulla configurazione di DNSSEC nella sezione gestione domini di ISPmanager
Impostare link incrociati all'interno della documentazione. Gli articoli correlati devono essere "collegati". Se gli articoli rappresentano una sequenza, assicurati di aggiungere frecce avanti e indietro alla fine di ogni testo.
Probabilmente, una persona andrà a cercare la risposta alla propria domanda non da te, ma su un motore di ricerca. È deludente se non ci sono link alla documentazione per motivi tecnici. Quindi, occupati dell'ottimizzazione per i motori di ricerca.
Problema 4. Un layout obsoleto ostacola la comprensione
Oltre ai testi scadenti, il design può rovinare la documentazione. Le persone sono abituate a leggere materiali ben impaginati. Blog, social network, media: tutto il contenuto è presentato non solo in modo bello, ma anche leggibile e gradevole per gli occhi. Quindi è facile capire il disagio di chi vede il testo come nello screenshot qui sotto.
In questo articolo ci sono così tanti screenshot e evidenziazioni che non aiutano, ma ostacolano la comprensione (l'immagine è cliccabile)
Non bisogna trasformare la documentazione in un lungo racconto con tanti effetti, ma le regole di base devono essere considerate.
Layout. Definisci la larghezza del testo principale, il font, la dimensione, i titoli e i margini. Coinvolgi un designer, e per accettare il lavoro o gestirlo da solo, leggi il libro di Artem Gorbunov "Tipografia e layout". Esso offre solo una delle molteplici visioni sul layout, ma è più che sufficiente.
Evidenziazioni. Definisci cosa richiede accento nel testo. Di solito si tratta di percorsi nell'interfaccia, pulsanti, frammenti di codice, file di configurazione, blocchi "Fai attenzione". Stabilisci come saranno le evidenziazioni di questi elementi e documentale nel regolamento. Tieni presente che meno evidenziazioni ci sono, meglio è. Quando ci sono troppe, il testo diventa "rumoroso". Anche le virgolette possono creare rumore se vengono usate troppo frequentemente.
Screenshot. Concorda con il team in quali casi siano necessari gli screenshot. Illustrare ogni passaggio non è affatto necessario. Un numero eccessivo di screenshot, compresi i pulsanti singoli, ostacola la comprensione e rovina il layout. Definisci le dimensioni e il formato delle evidenziazioni e delle didascalie sugli screenshot e documentale nel regolamento. Ricorda che le illustrazioni devono sempre corrispondere a quanto scritto e devono essere attuali. Ancora una volta, se il prodotto viene aggiornato regolarmente, sarà difficile tenere traccia di ogni elemento.
Lunghezza del testo. Evita articoli troppo lunghi. Suddividili in parti e, se non è possibile, aggiungi un sommario con link ancorati all'inizio dell'articolo. Un modo semplice per rendere l'articolo visivamente più corto è nascondere i dettagli tecnici, apprezzati solo da un ristretto numero di lettori, dietro un spoiler.
Formati. Combina diversi formati negli articoli: testo, video e immagini. Questo migliorerà la comprensione.
Non cercare di mascherare i problemi con una bella impaginazione. Onestamente, speravamo che il ‘packaging’ potesse salvare la documentazione obsoleta — non è andata così. Nei testi c'era così tanto rumore visivo e dettagli superflui che le normative e il nuovo formato non sono stati d'aiuto.
Molto di quanto descritto sopra sarà determinato dalla piattaforma che utilizzi per la documentazione. Noi, ad esempio, utilizziamo Confluence. Anche con questo abbiamo dovuto lavorare. Se ti interessa, leggi il racconto del nostro web developer: .
Da dove iniziare i miglioramenti e come sopravvivere
Se la tua documentazione è vasta come quella di ISPsystem e non sai da dove cominciare, inizia dai problemi più gravi. I clienti non comprendono la documentazione — occupati di migliorarla, crea normative, forma gli scrittori. La documentazione è obsoleta — affronta i processi interni. Parti dagli articoli più popolari sui prodotti più richiesti: chiedi al supporto, guarda le analisi del sito e le ricerche sui motori.
Diciamo subito — non sarà facile. E nemmeno veloce. A meno che tu non stia iniziando ora e lo faccia subito nel modo giusto. Una cosa è certa — col tempo migliorerà. Ma il processo non finirà mai :-).
Fonte: habr.com
