Dokumentācijas izstrāde

Pēdējais mainījis Valdis Vītoliņš 2011-11-24 15:58

Dokumentēšanas metodes un rīki

Dokumentēšanas metodes un rīki ir 2cr mācību kurss, t.i. sešpadsmit 90-minūšu nodarbības un vēl aptuveni tikpat daudz laika patstāvīgam darbam. Iepazīsimies ar konkrētu dokumentācijas izstrādes metodi, kura piemērota darbam ar atvērtā koda rīkiem (Open Office, Java un XML). Rīku komplekts veidots speciāli šim mācību kursam. Savukārt metodoloģijas un izmantoto jēdzienu ziņā esam daudz aizguvuši no citām pasaulē pazīstamām dokumentēšanas pieejām - kursa saturā attiecīgajās vietās centīsimies ievietot atsauces.

Kursa tēmu saraksts

1.1 Dokumentēšanas metožu pārskats
1.2 Dokumentēšanas mērķi, metodes pamatjēdzieni, fāzes. 1.3 Dokumentācijas veidošanas problēmas. 1.4 Vēsturisks metožu pārskats, autoru, lasītāju, organizāciju grūtības. 1.5 Kursā izklāstītās metodes pārskats: Galvenās fāzes, fragmentēšana un marķēšana, iespēja ātrāk sameklēt vajadzīgo.
  1. Analīzes fāze: Projekta prasību apskats, mērķauditorijas un dažādu apstākļu noskaidrošana
    1. Analīzes fāze: Projekta mērķu un sagaidītās atbildes apraksts, auditorijas analīze
    2. Analīzes fāze: Satura apjoma analīze, attēlošanas mēdija analīze, projekta plāns.
  2. Projektēšanas fāze dokumentēšanā: Tēmu saraksta veidošana, informācijas tipi, principi un vadlīnijas
    1. Tēmu saraksts: Tēmu un prasmju identificēšana
    2. Seši informācijas tipi (aizgūts no IM): Princips, process, procedūra, jēdziens, struktūra, fakts
    3. Projektēšanas principi: fragmentācijas (chunking) princips, svarīguma (relevance) princips, markēšanas (labeling) princips, konsekvences (consistency) princips. 
    4. Bloki un mezgli (blocks and maps): Modulāra un atkalizmantojama teksta veidošana
  3. Izstrādes fāze dokumentēšanā: Dažāda veida informācijas tipu praktiska attēlošana
    1. Principu attēlošana: Likumu un noteikumu aprakstīšana
    2. Procesu attēlošana: Fāzu un aprakstu saraksti, nosacījumu apraksti
    3. Procedūru attēlošana: Procedūru soļi, procedūru diagrammas
    4. Jēdzienu attēlošana: Definīciju saraksti, vispārinoši un kategorizējoši jēdzieni.
    5. Struktūru attēlošana: Sastāvdaļu apraksta tabulas, struktūras fragmentēšana
    6. Faktu attēlošana: Frāzes un teikumi, saraksti, tabulas, attēli
    7. Lielu artifaktu veidošana: Satura hierarhijas veidošana atbilstoši dokumentēšanas mēdijam
    8. Stila vadlīnijas: Teksta, sarakstu, tabulu, diagrammu u.c. veidošanas vadlīnijas
  4. Dokumentācijas testēšana un labošana: Pēcizstrādes un uzturēšanas posms
    1. Dokumentācijas profesionālapskate (peer-review): Vadlīnijas un procesa organizēšana
    2. Beta testēšana: Ierosinājumu apkopošana no mērķauditorijas
    3. Kļūdu labošana un kļūdu sarakstu veidošana
    4. Atgriešanās pie analīzes: Mērķu sasniegšanas un sagaidītās atbildes izvērtēšana
  5. Dokumentācijas izstrāde ar Open Office: Konsekvents stils, struktūra un atsauces, rakstot lietotāju rokasgrāmatas, mācību materiālus vai citus tehniskus sacerējumus
    1. Direktoriju un failu izkārtojums, versiju pārvaldība: Vienavota (single-sourcing) pieeja, Subversion serveris un klients
    2. Metainformācija failiem un to fragmentiem: Kā apzīmēt fragmenta atribūtus tā, lai tie būtu redzami un atkalizmantojami.
    3. Stilu definēšana vieglākai fragmentācijai (chunking): OLE-tipa prezentāciju bildīšu un īpašu piezīmju ievietošana, tabulas un attēli ar virsrakstiem un tabulu/attēlu rādītāju, teksta dekorācijas
    4. Dažādu problēmu risinājumi: Īpašie simboli, matemātiskas izteiksmes, rindu un lappušu laušana
    5. Open Office dokumentu apstrāde kā XML: Dokumentu eksports uz XML, transformācija no prezentācijas struktūras uz priekšmetapgabala XML struktūru, validācija un grupēšana
  6. Dokumentācija tīmekļa mēdijā: Izejas dokumentu pārvēršana par HTML un navigējams attēlojums
    1. XML pārveidošana par HTML: Viena liela vai vairāku mazu HTML veidošana no priekšmetapgabala XML (rīki - Scala vai XSLT)
    2. XSLT pārveidojumi: Priekšmetu (jēdzienu) rādītājs, tabulu/attēlu rādītājs, satura rādītājs
    3. Publiskošana tīmeklī ar viki rīkiem: Navigācija ar vienu izvēlni plus lasīšana pa sanumurētām daļām vai arī ar pogām (uz priekšu, atpakaļ, uz augšu)
    4. Nesaistē navigējams dokumentācijas kopums: Kā veidot CHM (Windows Help) un līdzīgus e-grāmatu formātus
  7. Dokumentācija papīra mēdijā: Kā veidot drukājamus PDF dokumentus
    1. Apache FOP rīka noskaņošana: Unikoda fontu pievienošana
    2. Satura transformācijas ar Apache FOP: Heterogēnas XML struktūras attēlošana par FO un PDF
    3. Satura transformācijas ar JasperReports: Kopsavilkumu, tabulu un diagrammu izveidošana
    4. Pēcapstrādes manipulācijas ar PDF: Vairāku lappušu savietošana vienā, A5-formāta bukleti (iText), dalīšana pa lappusēm vienādi uz A4 un US papīra
  8. Sadarbības organizēšana: Kā kolektīvi veidot dokumentus, lietojot viki-rīkus vai rediģējot informācijas kartītes ar konsekventu struktūru.
    1. Lietotāja definētās dokumentu klases XWiki: informācijas kartīšu radīšana ar konkrētu lauku izvietojumu
    2. Velocity makrokomandas: Kā definēt makrokomandas terminu attēlošanai, attēlu/pielikumu iekļaušanai, u.c.
    3. Receptes, kas pildāmas pa soļiem (Odo.lv stilā): Pietiekami sarežģītas informācijas kartītes izveidošana
    4. Orientēšanās kartotēkā: XWiki kartīšu strukturēta attēlošana un meklēšana
    5. XWiki sadarbība ar ārējām lietojumprogrammām: RDF, JSON datu eksports
  9. Saturpārvaldības sistēmas:
    1. Dokumentu veidošanas rīki
    2. Dokumentu repozitoriji, versionēšana un versiju kontrole
    3. Dokumentu apstrāde dažādos prezentācijas formātos
    4. Viki rīki (MediaWiki, XWiki), Web vietņu rīki (Drupal, Wordpress), forumu rīki (PhpBB, JForum)
    5. Scenāriju valodas (scripting languages) kā "līmlente", integrācija ar JavaScript, JSON, Velocity
    6. Informācijas attēlošana mikšļa (mashup) lietojumprogrammās
    7. Metainformācija, semantiska meklēšana un zināšanu pārvaldība

Praktiskie darbi

  1. Atbilstoši pasniedzēja dotajam scenārijam, veikt analīzi un izstrādāt dokumentēšanas projekta plānu 
  2. Fragmentēt un marķēt doto e-pasta ziņojumu vieglākai uztveramībai
  3. Identificēt informācijas tipus kādā lietotāja rokasgrāmatā, piedāvāt labojumus
  4. Izmantojot Open Office, veikt informācijas fragmentu (bloku, mezglu) izstrādi kādam savam projektam pēc izvēles
  5. Pārveidot dokumentus priekšmetapgabalam raksturīgā XML. Veikt priekšdarbus tā publiskošanai tīmeklī
  6. Pārveidot XML drukājamā formā, pārveidot par A5 bukletu
  7. Importēt dokumentus XWiki vidē, pievienot tagus u.c. metadatus vieglākai atrašanai
  8. Izmantot lietotāja definētas XWiki klases

Jautājumi, kas noskaidrojami kursa gaitā

  1. Kā Open Office dokumentā ātri ievietot noteikta veida speciālos simbolus (N-dash, M-dash, smart-quote, u.c.)
  2. Vai labāk lapas numurēt visā dokumentā, vai arī lietot divdaļīgu lappušu numerāciju "1-2", utt. Kādēļ saturam/priekšvārdam numerācijā lieto atsevišķu virknīti ar romiešu cipariem?
  3. Vai Open Office atšķiras parasts (Ctrl+I) stila kursīvs no Character Styles > Emphasis stila kursīva?
  4. Kā mainīt ar Insert > Indexes and Tables ievietotā satura rādītāja virsrakstu (Table of Contents) un arī izvietojuma stilu?
  5. Tabulām izveidot konsistentas 0.25'' atkāpes; aiz tabulas Open Office iedzimtajā izkārtojumā izveidot nelielu balto maliņu.
  6. Kā panākt, lai vārdu izcēlumi (Strong Emphasis, etc.) parādītos rindkopas stilam atbilstošā burtu izmērā. Negribas ieviest dažādus "apakšizcēlumus", kas atšķiras tikai ar fonta izmēru.

Ilustratīvi piemēri

Lai kursa dalībniekus iedvesmotu veidot pašiem savu dokumentāciju atbilstoši labiem paraugiem, ir jāizveido daži (vēlams arī reālistiski) dokumentu piemēri, kas izveidoti atbilstoši metodoloģijai un pastāvošajām labajām praksēm.

  1. Procedūras piemērs: Datoru iepirkšanas procedūra Latvijas skolās
  2. Lietotāja pamācība: Kā rīkoties ar kafijas automātu, Kensingtona kabeli

Atkāpes no Information Mapping rekomendācijām

  1. Lappuses tiek numurētas visā grāmatā pēc kārtas (izņēmums varētu būt saturs/priekšvārds, kur izmantojam tradicionālos romiešu burtus)
  2. Taupām vietu - ja ir sagaidāms, ka "augsta līmeņa" nodaļās (vingrinājumu atrisinājumos vai tml.) būs nedaudz teksta, tos nesākam nepāra lappusē; varbūt vispār neievietojam lappuses pārtraukumu.
  3. Ja teksta bloks seko tūlīt aiz kādas sadaļas virsraksta (un ja tas ir ievads), tad šo iezīmi (label) "Ievads" drīkst nerakstīt -  tā ir noklusēta.
  4. Pievienojam jaunu posmu (phase) - oriģinālā ir "define", "design", "develop" posmi. Tulkojumā ir "plānošana", "projektēšana", "izstrāde" un "pārbaude" - ar to šis process kļūst līdzīgāks parastai softa izstrādei, kur pēc izstrādes ir arī testēšana. Galvenais "pārbaudes" posma galaiznākums - labojumu saraksts. 
Tagi:
Izveidojis Kalvis Apsītis 2010-05-01 13:40
    
This wiki is licensed under a Creative Commons 2.0 license
XWiki Enterprise 6.4 - Documentation