Această postare de invitat este de Carlos Evia, dr., Directorul de scriere profesională și tehnică la Virginia Tech.

luând

Subiectul DITA Troubleshooting este una dintre caracteristicile „noi” din versiunea 1.3 a standardului. Cu toate acestea, depanarea a fost în jurul lumii DITA de câțiva opt ani buni acum.

O arhivă SourceForge de plug-in-uri pentru DITA Open Toolkit găzduiește încă o specializare în depanare lansată în octombrie 2007. Subiectul de depanare din 2007 suna ca o vizită la medic, cu etichete precum tsSymptoms, tsCauses, tsDiagnose și tsResolve (tsTake2Aspirins a fost prea lung, Cred).

Abia în iulie 2014, Comitetul tehnic pentru adoptarea DITA a anunțat subiectul de depanare ca un tip de conținut formal nou în standard. Comitetul a lansat apoi versiunea finală a cărții albe folosind DITA 1.3 Troubleshooting, scrisă de Bob Thomas. Cartea albă prezintă rațiunea subiectului de depanare și oferă exemple și șabloane detaliate, precise, concentrându-se pe o structură de perechi de informații cauză-remediu pentru a completa subiectul.

În acea perioadă, am fost invitat să conduc un proiect de consultanță pentru un client care are nevoie de un manual online pentru procesele legate de fabricarea cartonului (nu afacerea lor reală; doar un exemplu pentru acest post). Clientul a dorit să aibă informații „cum să” bazate pe web pentru operatorii responsabili cu procesele de carton ondulat și tăiat sub presiune (nu procesele reale pe care le-am documentat). În timp ce am reunit o echipă de profesori și studenți în comunicare tehnică și informatică, în timpul unei întâlniri timpurii, clientul a dezvăluit că manualul trebuie să se concentreze asupra depanării. Asta mi-a zgâriat mâncărimea pentru că am luat subiectul de depanare.

La șapte luni de la proces, pe măsură ce încheiem proiectul, aici împărtășesc câteva lecții învățate din experiența mea cu tema de depanare.

Efectuați o analiză a cauzei principale

Analiza sarcinilor, colectarea și analiza documentației vechi și interviuri. Aceste arme tradiționale pentru comunicarea tehnică nu sunt probabil eficiente pentru a obține informații de depanare. Când a căutat perechi cauză-remediu, echipa (condusă de personalul resurselor umane al clientului) a efectuat o analiză a cauzei radicale. În cea de-a 3-a ediție a cărții Root Cause Analysis, Latino & Latino a definit-o prin includerea a patru definiții diferite! Pentru cea de-a 4-a ediție (care include un al 3-lea latino în lista de co-autori), acestea simplifică definiția analizei cauzei radiculare ca „stabilirea stabilirii unor lanțuri de factori logice complete, bazate pe dovezi, strâns cuplate, de la cele mai puțin acceptabile consecințe până la cele mai profunde cauze semnificative care stau la baza ”(p. 15).

Instrumentul specific pentru cauză și efect pe care l-am folosit pentru acest proiect de depanare a fost o sesiune de cinci de ce, care poate fi utilizată pentru a „pune la îndoială fiecare cauză identificată dacă este un simptom, o cauză de nivel inferior sau o cauză rădăcină” și „continua căutarea adevăratelor cauze fundamentale chiar și după constatarea faptului că s-a găsit o posibilă cauză ”(Andersen și Fagerhaug; 2000, p. 117). Cele cinci de ce exercițiu au implicat supraveghetori, operatori cu diverse niveluri de expertiză și personal din departamentul de resurse umane al clientului. La sfârșit, am avut o serie de tabele care documentează condițiile, oferind tipul de perechi cauză-remediu specificate în hârtia albă DITA Adoption TC.

Prioritizați condițiile și soluțiile

O sesiune lungă de analiză a cauzelor profunde cu supraveghetori, utilizatori și manageri poate fi prea exhaustivă pentru un ghid de depanare destinat unui public de operatori de mașini. Nu uitați niciodată utilizatorii intenționați ai livrării și nevoile lor unice. În timpul experimentului de cinci de ce am ieșit cu unele condiții care au avut mai mult de 15 posibile perechi cauză-remediu. Toate au fost interesante și relevante pentru unele aspecte ale producției de carton. Cu toate acestea, unele s-au întâmplat cel puțin o dată pe săptămână, iar altele au fost legende aproape urbane. Multe dintre soluțiile lor implicau supraveghetori de schimbare sau tehnicieni. Am filtrat rezultatele pe baza a) nevoilor reale ale publicului în ceea ce privește domeniul de aplicare al proiectului și b) frecvenței la nivelul producției.

Vă dați seama că depanarea este un subiect excelent pentru început

Studenții care nu au fost niciodată expuși la DITA au avut o scurtă curbă de învățare pentru crearea subiectelor de depanare. Elevii știau despre principiile documentării eficiente, minime și ale scrierii convingătoare. Cu toate acestea, cunoștințele lor despre concept-sarcină-referință au fost limitate la 5 minute
prezentare. Pentru ei, DITA era în principal o gramatică de depanare. Spre deosebire de studenții care au început cu un curs DITA 101 și au trebuit să lucreze cel puțin o jumătate de semestru cu standardul, noii autori de depanare au avut o tranziție lină către scrierea bazată pe subiect.

Poate pentru că o sarcină sau un concept ca o bucată izolată de informații are nevoie de o hartă și o transformare pentru a avea sens. Subiectul de depanare, pe de altă parte, are o cauză și o soluție și poate încorpora elemente ale unei sarcini. Subiectul oferă o satisfacție instantanee autorului care îl poate vedea ca pe un produs mic.

Amintiți-vă că conrefurile contează

A avea noi autori DITA care nu știau prea multe despre standard a adus și probleme. Studenții fără experiență anterioară DITA au fost buni la învățarea etichetelor din spatele subiectului de depanare și au însușit linkuri de referințe încrucișate. Dar când a fost vorba de utilizarea conrefurilor, a trebuit să numim un inspector. Le-am numit „poliția conref”. La urma urmei, o lamă plictisitoare pe o mașină de tăiat carton poate fi cauza multor condiții, iar soluția va fi întotdeauna „cere întreținere pentru a înlocui lama”.

Poliția conref era însărcinată să discute frecvent cu autorii și să propună soluții de conref fără a intra prea adânc în conceptul și mecanica refolosirii.

Rețineți că diagramele de flux elimină conținutul bun

Un subiect de depanare poate include mai multe perechi cauză-remediu (starea „umidității” în ondulare, de exemplu, are multe cauze posibile). Când vă confruntați cu scenarii complexe cu multe soluții, cartea albă DITA Adoption TC propune utilizarea diagramelor de flux statice în interiorul unui
etichetă imagine. Învăț despre DITA la nivel de facultate de opt ani și le spun întotdeauna studenților mei că conținutul bun va muri în diapozitivele PowerPoint. O, băiete, nu eram pregătit să mă ocup de diagramele de flux statice. Uitați de conținutul bun care a murit din cauze naturale de export; diagramele de flux ucid conținut bun fără milă. O schimbare minoră, aplicația de filtrare sau greșeala de scriere vă trimite înapoi la OmniGraffle și nu permite personalizarea ușoară.

Poate că soluția vine, cu proiectul DITA-to-flowchart al lui Jang Graat, pe care l-a introdus anul trecut la DITA Europe. Vom aștepta și vom vedea.

Găsiți o soluție pentru „remediu”

Ca etichetă și titlu, „remedierea” nu a rezolvat problemele în acest caz. Poate că a fost situația unică a acestui proiect, în care personalul de conducere al clientului și majoritatea echipei de autor și de dezvoltare erau hispanici. Nu este nimic etimologic în neregulă cu termenul, dar cu cât am vorbit mai mult despre el, pentru noi „remediu” suna ca o soluție ieftină și rapidă. Gândiți-vă la stigmatul atașat „scrierii corective” în facultate. Am decis să folosim „Soluție” în titlul fiecărei secțiuni, dar eticheta este încă un remediu și nu putem schimba acest lucru.

Îndoiți regulile (pentru a ajuta utilizatorii)

Faceți documentația ușor de găsit. Nu este aceasta una dintre caracteristicile IBM ale informațiilor tehnice de calitate? (Carey și colab. 2014). Pentru acest proiect, livrabilul web principal avea un index generat de DITA și o casetă de căutare. Cu toate acestea, utilizatorii au trebuit să identifice cutii defecte, privind imaginile care prezintă cele mai frecvente condiții care afectează procesele de ondulare și tăiere. O soluție rapidă, fără a specializa sau modifica XSLT-urile, a fost crearea unui catalog vizual de defecte. Pe harta principală, subiectul referitor la conceptul c-corrugatingtrouble.dita a avut un copil pentru fiecare afecțiune documentată.

Imaginile proveneau din fiecare subiect de depanare, unde fuseseră incluse (blasfemie!) Incluse în scurta descriere. A funcționat, iar utilizatorii au putut identifica condițiile pornind de la o cutie defectă.

Subiectul de depanare, așa cum este inclus în standardul DITA 1.3, a meritat așteptarea lungă. Este un tip de conținut foarte necesar, pe care autorii îl pot înțelege și adopta cu ușurință. Acum trebuie doar să-mi actualizez materialele didactice pentru a extinde limbajul concept-sarcină-referință.

Referințe

Andersen, B. și Fagerhaug T. (2000) Analiza cauzei radiculare: instrumente și tehnici simplificate. Milwaukee, WI: ASQ Quality Press.

M. Carey, M., McFadden Lanyi, M., Longo, D., Radzinski, E., Rouiller, S. și Wilde, E. (2014). Dezvoltarea informațiilor tehnice de calitate: un manual pentru scriitori și editori. Upper Saddle River, NJ: IBM Press.

Latino, R. J., Latino, K. C. și Latino, M. A. (2011). Analiza cauzei radiculare: îmbunătățirea performanței pentru rezultatele de jos. A 4-a ed. Boca Raton, FL: CRC Press.