Fie că e vorba de documentația utilizată intern de echipele de dezvoltare/producție, sau despre documentația suport pentru clienți, în spatele acestora se află de cele mai multe ori un Technical Writer (TechWr). În prima parte a articolului (publicată într-un număr anterior) am abordat activitățile și provocările unui Technical Writer. în această a doua parte ne propunem să expunem și să analizăm tehnicile și instrumentele pe care le folosește un TechWr.
Deprinderi de comunicare - Un TechWr trebuie să poată comunica informațiile (în formate diferite) în mod clar, ușor de înțeles și de urmat.
Orientarea către detalii - Un TechWr trebuie să identifice și să clarifice toate asumpțiile și lucrurile considerate ca fiind "înțelese de la sine". Poate că unii utilizatori mai puțin experimentați nu își vor asuma inițiativa de a apăsa pe butonul "Finalizare" în cadrul unei instalări, dacă acest pas nu este trecut explicit în instrucțiuni.
Imaginație - Un TechWr trebuie să se poată pune în locul unei persoane care vede acel produs sau program software pentru prima dată și care nu are deloc experiență în interacțiunea cu acesta.
Lucrul în echipă - Un TechWr face parte dintr-o echipă, colaborând cel puțin cu colegii ce sunt responsabili de partea tehnică a produsului sau a programului ce are nevoie de documentație tehnică.
Deprinderi tehnice - Un TechWr este cel puțin și un tester, deoarece trebuie să se asigure că, în cazul unui program software, acesta face chiar ceea ce se spune în instrucțiuni și nu altceva. Mai mult, TechWr trebuie să poată explica în mod simplu informații tehnice complexe.
Crearea de conținut este influențată de cunoașterea domeniului despre care se scrie, de cunoașterea paradigmelor TechWr și a unor instrumente (tools) specifice. Toți acești factori influențează livrarea documentației. Vom detalia mai jos relația dintre acești factori.
Documentația unui produs nu poate fi livrată oricum. În funcție de domeniul în care se lucrează, documentația va trebui realizată în conformitate cu o serie de standarde de calitate internaționale: ISO/ IEC/ IEEE, ANSI, DIN, VDI . În absența unei documentații care să răspundă standardelor internaționale, produsele nu pot fi comercializate, nu pot fi supuse auditului, nu pot fi reglementate sau patentate. Un TechWr nu poate cunoaște toate standardele din toate domeniile, dar are obligația de a identifica și de a învăța care sunt standardele ce se aplică domeniului de activitate despre care scrie, iar companiile au obligația de a aloca timp acestei activități de cercetare.
În ceea ce privește standardele internaționale pe care trebuie să le respecte documentația software, menționăm:
| Standard ISO/IEC/IEEE | Descriere |
|---|---|
| ISO 26511: 2018 | Systems and software engineering - |
| Requirements for managers of information | |
| for users of systems, software, and | |
| services | |
| ISO 26512: 2018 | Systems and software engineering - |
| Requirements for acquirers and suppliers | |
| of information for users | |
| ISO 26513 | Systems and software engineering - |
| Requirements for testers and reviewers | |
| of user documentation | |
| ISO 26514 | Systems and software engineering - |
| Requirements for designers and | |
| developers of user documentation | |
| ISO 26515 | Systems and software engineering - |
| Developing information for users in an | |
| agile environment | |
| ISO 82079 - 1:2019 | Preparation of information for use |
| (instructions for use) of products |
Tabel 1: Standarde ISO/IEC/IEEE pentru industria software
După ce standardele internaționale sunt înțelese, trebuie decisă tehnica de scriere sau paradigma cu care decidem să lucrăm (Boiko 2005). Pentru industria software și industriile conexe, paradigma cea mai răspândită este DITA (Darwin Information Type Architecture). DITA presupune următoarele principii (Closs 2016):
DITA se bazează pe principii precum specializare și moștenire sistemică (Darwin).
DITA cataloghează tipurile de informație, contextul în care se folosesc acestea și structura internă a unei unități minimale de informație (topic) (Information Typing).
DITA se bazează pe standardul XML, dar este mai mult decât atât, fiind un proces și o metodă de lucru (Architecture).
DITA presupune separarea scrierii conținutului de instrumentele ce publică conținutul.
DITA este o metodologie, un standard și o aplicație XML care a fost integrată în majoritatea instrumentelor CMS (Content Management Systems) (Gollner 2015) folosite de TechWr. Sistemele CMS (sistemele ce gestionează ciclul complet de creare - organizare - publicare de conținut) ce au integrat DITA se bazează pe DITA Open Toolkit (DITA OT) care cuprinde elemente de limbaj, fișiere schema (DTD sau XSD), mostre de fișiere și transformatori. Pentru a lucra cu DITA, minimul necesar este DITA OT și un editor XML. Acestea vă vor permite să scrieți conținut DITA și să publicați conținutul în mai multe formate (RTF, PDF, HTML etc.).
Pe lângă metodologia DITA, există o serie de alte metodologii pentru structurarea informației, unele specifice doar anumitor domenii. Le prezentăm în cele ce urmează.
| Paradigmă | Descriere |
|---|---|
| DITA | Folosită pentru documentarea produselor |
| software, cu posibilitatea de | |
| extindere către alte domenii; Standard | |
| internațional gratuit gestionat de OASIS | |
| și IBM, cunoscut sub numele DITA OT; | |
| Standard XML flexibil ce permite | |
| specializarea adaptivă a structurii | |
| conținutului, scrierea ghidată de | |
| reguli, reutilizarea; Unitatea de bază | |
| este topicul, o unitate de sine | |
| stătătoare care descrie, explică, oferă | |
| detalii suplimentare despre o temă; | |
| Topicurile standard: concept, task | |
| (instrucțiune), reference (referință), | |
| glossary (glosar), troubleshooting | |
| (soluții tehnice); Implementat de multe | |
| editoare XML și sisteme CMS; Limitări | |
| semantice la nivelul structurii unui | |
| topic. | |
| DocBook | Folosită pentru publicațiile în formă |
| printată sau cele care au structura unei | |
| cărți, de obicei publicații de | |
| dimensiuni foarte mari; Standard XML cu | |
| structură generică și semantică mai | |
| limitată decât standardul DITA; Unitatea | |
| de bază este modulul definit la nivel de | |
| capitol sau sub-secțiune; Include | |
| fișiere predefinite (dar customizabile) | |
| de tip "stylesheet" pentru a publica | |
| conținutul ca HTML, HTML Help sau PDF; | |
| Momentan, standardul este disponibil ca | |
| XML DTD sau XML Schema; Implementat de | |
| multe editoare XML și sisteme CMS. | |
| S1000D | Folosită în industria militară sau |
| aviație, dar recent introdusă și în | |
| industria feroviară, navală sau energie | |
| eoliană pentru ghiduri ce țin de | |
| utilizarea și mentenanța produsului; | |
| Trebuie interpretată și customizată | |
| pentru fiecare industrie; Standard XML | |
| ce permite flexibilitate, scrierea | |
| ghidată de reguli, reutilizarea; Unitate | |
| de bază este modulul: *descriptive | |
| information* (informație descriptivă), | |
| fault information (informație probleme | |
| tehnice), procedural information | |
| (informație procedurală), *maintenance | |
| planning information* (informație pentru | |
| planificarea mentenanței), *parts | |
| information* (informație referitoare la | |
| componente); Oferă reguli pentru | |
| crearea, gestionarea, distribuția | |
| documentației, dar nu oferă soluții | |
| unice/fixe pentru problemele din timpul | |
| procesului de documentare Implementează | |
| un standard de limbă engleză specific | |
| acestei paradigme: ASD-STE100 Simplified | |
| Technical English. | |
| PiMod | Folosită pentru industria |
| manufacturieră/mașinării/fabrici; | |
| Standard open-source customizabil; | |
| Unitatea de bază este modulul de tip: | |
| task (instrucțiune/ sarcină de lucru), | |
| descriptive (descriere), diagnosis | |
| (diagnostic), tools (instrumente), | |
| task intervals (interval între sarcini | |
| de lucru), lubrication (lubrifiere), | |
| glossary (glosar); Clasificarea se | |
| face per produs și per tip de | |
| informație; Se poate integra cu multe | |
| sisteme CMS, unele având principiile | |
| PiMod integrate nativ. | |
| Information Mapping | Folosită pentru dezvoltarea materialelor |
| de tip eLearning ; Structurarea | |
| informației se bazează pe rezultatele | |
| studiilor cognitive; Unitățile de bază | |
| sunt block (sau topic) și map (hartă = | |
| mai multe elemente block, având un | |
| key block ce conține informația | |
| principală și elemente block | |
| adiționale); Tipurile de informație | |
| standardizate sunt: procedure | |
| (procedura), process (procesul), | |
| principle (principiul), concept | |
| (conceptul), structure (structura), | |
| fact (elementul faptic), | |
| classification (clasificarea). | |
| Functional Design | Folosită pentru manualele ce explică |
| programele software; Inițial bazată pe | |
| Teoria Actelor de Limbaj (Speech Act | |
| Theory); Restricționarea actelor de | |
| limbaj permise în redactarea de | |
| documentație: per text putem alege doar | |
| din actele de vorbire omologate, iar | |
| adăugarea de reguli de utilizare pentru | |
| fiecare act de vorbire asigură calitatea | |
| și consistența documentației; Unitățile | |
| de bază sunt: element markup > | |
| functional unit (unitate funcțională) | |
| > sequence pattern (secvențe) > | |
| information product (manual). |
Tabel 2: Paradigme de scriere/structurare
Pe parcursul carierei sale, un TechWr va folosi una sau mai multe din aceste metodologii. Prin urmare, cunoașterea elementelor de bază ale fiecărei metodologii este recomandată.
Scrierea efectivă de conținut poate fi realizată, teoretic cel puțin, în orice format, dar dacă dorim un conținut uniform, portabil, ușor de distribuit și integrat, actualizat fără efort astronomic, standardizat pentru a putea fi dezvoltat de orice membru al echipei, atunci redactarea într-un editor bazat pe limbaj markup este esențială.
Există o varietate de editoare, câteva dintre cele mai importante fiind: XMetaL, Structured FrameMaker, Oxygen XML Editor, Arbortext, XXE, Syntex Serna. Majoritatea sunt integrate cu DITA OT, ceea ce vă permite să scrieți topicuri în funcție de tip (concept - task - reference - glossary - troubleshooting) unde fiecare tip de topic vine cu un set de elemente și atribute permise și strict reglementate.
O componentă importantă o reprezintă schemele XML ce se pot salva în format DTD (Document Type Definition) sau XSD (XML Schema Definition) (Closs 2016). XML este un limbaj compus dintr-un set de reguli pentru stocarea informației. Avem nevoie de structuri diferite de date pentru fiecare tip de conținut pe care dorim să îl stocăm. Standardul DITA are o schemă XML actualizată de OASIS, perfect integrată de majoritatea editoarelor XML și de majoritatea sistemelor CMS. Pentru editarea în format XML, trebuie să cunoașteți interacțiunea dintre elemente și atributele elementelor. Elementele sunt incluse în taguri și pot conține date, alte elemente, atribute. Atributul este o definiție ce poate fi inclusă într-un element, fiind format din perechi nume-valoare (cheie-valoare).
Editoarele XML permit și stocarea de imagini, diagrame, video în format: TIFF, GIF, JPEG, BMP, SVG, CGM, MP3, JT.
În scrierea unui topic trebuie respectate structura XML convenită și o serie de principii ce asigură înțelegerea și asimilarea informației de către cititori (Bellamy et al 2012):
Conținutul este scris pentru o audiență specifică. Prin urmare, realizarea unei matrice conținut (topicuri) - audiență trebuie să fie primul pas în planificarea informației livrate clientului.
Structurarea informației influențează modul în care cititorul își activează/ amintește informația deja cunoscută. Prin urmare, vom porni de la informația deja cunoscută sau vom face comparații ale conținutului nou cu concepte deja cunoscute/elementare.
Informația trebuie marcată la nivel de componente (sign posting) pentru a fi urmărită ușor și logic. Prin urmare, pentru ca informația să poată fi scanată și parcursă ușor, aceasta va fi structurată în secțiuni marcate corespunzător (tabele, sub-titluri, liste etc).
Structurarea informației trebuie să permită cititorilor să clasifice informația și să stabilească corelații imediate. Prin urmare, împărțirea informației în definiții - liste - condiții - instrucțiuni - rezultat și marcarea corespunzătoare în taguri XML creează un orizont de așteptare predictibil pentru utilizatori.
Structura informației este relevantă pentru utilizator dacă este pusă în context, defalcată în unități ce pot fi înțelese ușor, dacă se bazează pe o comunicare clară, directă, bazată pe principiile sintactice și pragmatice ale limbii utilizate. Printre aceste principii menționăm:
coerența (un topic se referă la o temă pe care o clarifică);
utilitatea (un topic trebuie să ofere informații factuale corecte);
contextualitatea (un topic trebuie să poată fi utilizat în contextul unde este cel mai relevant);
coeziunea (un topic trebuie să conțină elemente referențiale care să facă referire clară la elementele prezentate anterior);
Deși limbajul XML ne facilitează formalizarea uniformă a informației, trebuie reținut că niciun instrument informatic nu ne va învăța cum să selectăm informația, cum să o adaptăm audienței, cum să o ierarhizăm.
Scriem informația cu intenția de a satisface o nevoie a cititorului. Astfel, putem aborda structurarea conținutului și tipul de instrucțiuni pe care le scriem punând accent pe produs, pe funcționalitate sau pe utilizator. Pentru a explica diferența dintre cele trei abordări, ne vom imagina că trebuie să structurăm un manual de utilizare pentru un aparat de fiert la abur (Tabelul 3).
Organizarea conținutului trebuie realizată la nivel de topic (unitate de bază), dar și la nivel de map (unitate intermediară formată din mai multe topicuri) sau publicație (unitate maximală). Sistemele CMS (Content Management Systems) (cunoscut și sub numele CCMS - Component-based Content Management System) permit gestionarea completă a conținutului (creare - organizare - distribuire - mentenanță) integrând principiile unei paradigme de scriere (sau a mai multor paradigme), un editor XML și o componentă de publicare (Gollner 2015).
Scrierea structurată într-un sistem CMS asigură:
Gestionarea unei surse unice pentru conținutul vostru (Single Sourcing);
Gestionarea modulară a informației cu scopul ca această să poată fi editată și revizuită; distribuit, reutilizată, controlată la nivel de versiune (Content Management & Authoring)
Gestionarea elementelor de tip metadata (Metadata Governance & Conditions);
În ceea ce privește publicarea efectivă de conținut, dacă utilizați un sistem de tip CMS sau CCMS, componenta de publicare în formate multiple e deja integrată în sistem, ceea ce înseamnă că după ce ați scris, organizat și marcat semantic conținutul, alegeți un template și generați publicația în formatul care corespunde acelui template: Windows Help, XHTML, CHM, PDF, Ebook etc. Printre instrumentele DITA utile pentru publicarea documentației menționăm: DITA OT, WebWorks ePublisher, Arbortext tools, RoboHelp.
Există o serie de sisteme alternative de gestionare a conținutului care nu vizează documentația tehnică, dar care pot furniza conținut pentru un sistem CMS:
Web Content Management Systems - gestionarea de website-uri sau produse bazate pe tehnologia web;
Document Management Systems - sistem intern de gestionarea a documentelor întregi, sursa o reprezintă departamentele interne ale companiei sau datele de la clienți;
Enterprise Resource Planning - un DMS scalat la nivelul unui enterprise pentru procese organizaționale globale pentru manufacturare (planificare, specificații, operații financiare, relații cu clienții);
O alternativă la un sistem CMS clasic poate fi utilizarea unor sisteme Wiki (Weinert & Brueggerman 2012) prin prisma următoarelor beneficii:
Permite scrierea colaborativă rapidă, din locații distribuite.
Permite scrierea modulară și reutilizarea conținutului.
Conținutul este centralizat și accesibil din toate locațiile, modificările fiind vizibile imediat.
Permite un ritm de învățare relativ rapid. Trebuie cunoscute următoarele elemente: Wikitext (sintaxa de bază) și MediaWiki (care permite inclusiv controlul versiunilor). Editoarele WYSIWYG pot simplifica munca semnificativ.
Nu necesită licențe și poate fi customizat.
Necesită efort de dezvoltare dacă se dorește publicare conținutului în variante printate.
Single-source publishing și localizarea necesită extensii.
Sperăm ca acum Technical Writer-ul și abilitățile sale să vă fie un pic mai familiare decât struțo-cămila sau furculicion-ul, iar data viitoare când întâlniți un asemenea "specimen hibrid" să recunoașteți cel puțin numele jobului său.
Achteling, M. - Component-based Content Management Systems, indoition.com,
Bellamy, L.; Carey, M. & Schlotfeldt, J., (2012) - DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA, IBM Press.
Boiko, B., (2005) - Content Management Bible, USA - UK: John Wiley&Sons.
Buehling, B. (2015) - Anatomy of an enterprise structure authoring system, tcworld Conference 2015
Cameron, S., (2011) - Enterprise Content Management: A Business and Technical Guide, BCS.
Closs, S. (2016) - DITA- the Topic-Based XML standard: a quick start, New York - London: Springer.
Gollner, J. (2015) - Practical steps towards integrated content management, tcworld Conference 2015
Kratchy, R. (2017) - Turning legacy documentation into user story based content, tcworld Conference 2017
Weinert, A. & Brueggermann, M. E. (2012) - Wiki as CMS, tcworld magazine, June 2012
**** Standard ISO/IEC 82079-1 (2012) - Preparation of instructions for use*
**** Standard ISO 26511 (2012) - Systems and software engineering. Requirements for managers of user documentation*