Dokumentalistid ja dokumentaatorid

Eile käis TechWR-L listist läbi selline ütlus:

“Documentalist”?  Is that a writer who does a mind reading act?  [—] Actually, yes, any tech writer who works with software developers has to be a mind reader to some extent.

Tõlge: “Dokumentalist? Kas see on kirjutaja, kes ühtlasi mõtete lugemisega esineb? [—] Tegelikult peab küll iga tehnosuhtleja, kes tarkvaraarendajatega suhtleb, oskama mingil määral mõtteid lugeda.”

Kuigi selles lauses on omajagu tõde, on see minu jaoks eriline hoopis teisel põhjusel. Nimelt on Raintree Estonias kombeks uut dokumenteerijat otsides paluda ka ingliskeelset kaaskirja, mis annab meile ülevaate kandidaadi inglise keele oskusest. Päris paljusid kandidaate paneb komistama just sõna “dokumenteerija” tõlkimine inglise keelde – paar levinumat varianti on olnud documenter ja documentator. Ilmselt ei teadnud kandideerija ingliskeelset terminit (eelistatavalt technical writer) ja otsustas tõlkimisele jõuga läheneda.

Muide – see üksinda ei diskvalifitseerinud kandidaate. Vähemalt üks “documenter” jõudis ka intervjuuni.

Raamat – “Developing Quality Technical Communication”

“Developing Quality Technical Communication: A Handbook for Writers and Editors” IBM Press, 2004. Autorid: Gretchen Hargis; Michelle Carey; Ann Kilty Hernandez; Polly Hughes; Deirdre Longo;
Shannon Rouiller; Elizabeth Wilde

Minu arvamuse sellest raamatust võib kokku võtta kahe punktiga. Esiteks – see on parim raamat, mida ma tehnosuhtluse kohta olen lugenud. Ja teiseks – see ei ole kuigi hea valik esimeseks raamatuks, mida tehnosuhtluse kohta lugeda. 🙂

Jätka lugemist

DITA varjuküljed

Eelnevatest postitustest võib jääda mulje, nagu ma oleks tulihingeline DITA entusiast. Mingil määral ongi see nii – kuna ma alustasin dokumenteerijana tühja koha pealt, ei ole mul mingit formaalset erialast haridust ja seega ka mingit süsteemi, kuidas dokumenteerimisele läheneda. DITA kui moodne avatud standard kõlas just sellena, mida vaja – see on suhteliselt paindlik ja samas piisavalt formaalne.

Samas ei ole ka DITA täiuslik. Mark Baker on oma blogis avaldanud viieosalise kriitilise artikli The Tyranny of the Terrible Troika: Rethinking Concept, Task, and Reference DITA negatiivsete külgede kohta, millest üritan olulisemad punktid siin välja tuua.

Jätka lugemist

Info struktureerimine

DITA arhitektuuri keskne osa, millele viitavad ka kaks keskmist tähte, on informatsiooni struktureerimine vastavalt selle tüübile. Samas ei ole see ainult DITA jaoks vajalik – korralikult struktureeritud info aitab lugejal kiiremini vajalikku infot leida ja sellest aru saada. Lisaks DITA mõiste-ülesanne-viide struktuurile on ka muid alternatiive.

Jätka lugemist

DITA Open Toolkit

Eelnevale DITA ülevaatele jätkuks mõni sõna DITA Open Toolkiti kohta.

DITA Open Toolkit (DITA-OT) on kogum peamiselt Javal põhinevaid komponente, mis võimaldavad DITA sisust erinevaid väljundeid toota. Vaikimisi toetatud väljundid on:

  • XHTML
  • PDF
  • RTF (mõnede piirangutega)
  • ODT
  • DocBook
  • HTML Help
  • Eclipse Help
  • JavaHelp
  • troff

DITA-OT abil väljundi genereerimine sarnaneb koodi kompileerimisele – protsess algab Anti ehitusskriptidega, mis võtab DITA teemad, laseb need läbi Xerxese parseri ja viib need kas Xalani või Saxoni XSLT protsessori abil soovitud kujule. Kui väljundiks on PDF, siis vaikimisi kasutab DITA-OT selleks FOP XSL-FO protsessorit, kuid selle asemel saab kasutada ka mõnda muud.

Lisaks nimetatud tarkvarale sisaldab DITA-OT ka kogu DITA standardit koos spetsialisatsioonidega ja mõningaid pluginaid, mis täiendavad DITA standardfunktsioone.

DITA – mis ja milleks

Kui eestikeelsetelt veebilehtedelt otsida sõna DITA, siis on tulemuseks ainult ühe teatud burleskikaunitari nimi. Samas on USAs selle kohta ilmunud mitmeid raamatuid, sadadest veebilehtedest ja konsultantidest rääkimata, ning seda peeti paari aasta eest tehnosuhtluse tulevikuks. Seega – millega siis tegu on?

Jätka lugemist