Hea dokumentatsiooni tellimise saladus

0 Avamõte

• Programmeerijatele ei meeldi dokumenteerida
• *Why Programmers Hate Documenting? – Joel on Software

1 Mudelid

+---------------+----------------------+
|Progemine      |  Tarkvara kasutamine |
+---------------+----------------------+

            +----------->

+------------+----------+--------------+
|Progemine   | Müük     |  Kasutamine  |
+------------+----------+--------------+


+-----------------+--------------------+
|Progemine|Dok ne | Müük    |Kasutamine|
+-----------------+--------------------+

    Dok-ne +-----> Dok-ni kasutamine

• Progemine -> Tarkvara kasutamine
  • *Build and They Will Come
  • Programmeerimine -> Müük -> Kasutamine
  • Programmeerimine -> Dokumenteerimine -> Müümine
  • alamvoog:
    • Dokumenteerimine -> Dokumentatsiooni kasutamine

2 Dokumentatsiooni juures oluline; palju asju, mõned:

• olemasolu
• ülesleitavus
• navigeeritavus
• seletab asju ka sisuliselt
  • Märkus. Inimesi, kellel on võime/tahe IT-s asju lahti seletada, on väga vähe.
• Lasting value
• Six-page memo (Jeff Bezos/Amazon)
• *The Missing Manual – O’Reilly
  • Mis on toote YYY dokumentatsioonis puudu? Juhend, mis seletab lahti XXX olemuse

3 Ambitsioonitasemed

Kui peame dokumentatsiooni oluliseks, soovime head dokumentatsiooni.

• tase 0: mingi dokumentatsioon, suvalises vormingus (PDF)
• …
• navigeeritav, kontekstiläbuta, professionaalse kujundusega dokumentatsioonisait

4 Dokumentatsiooni tootmise töövoog: nõuded

• kaks vaatepunkti:
  • dokumentatsiooni tootja
  • dokumentatsiooni kasutaja
• mõlemal peab olema hea
• tootja valib ise tööriista
• kasutajale aga esitatakse kasutaja soovitud kujul
• need kaks ei tarvitse ühte lamgeda
• järelikult on vaja teisendusi, andmete viimist ühest vormingust teise
• teisendusi ei saa vältida, see on IT olemus
• samal ajal, vahelülid on saatanast

5 Dokumentatsiooni minisait: millega teha?

• Jekyll, Hugo, Middleman, MkDoc …
• häid vahendeid on raske leida

6 Üks võimalik töövoog

• Markdown - laialtlevinud märgendkeel
• GitHub - versioonihaldustarkvara
• Git Bash - Git versioonihalduse tööriist
• Jekyll - staatilise veebisaidi generaatorrakendus
  • Kramdown - Jekylli preprotsessor (eeltöötleja)
• HTML5 - universaalne veebikeel
• CSS3 - veebi kujunduskeel
• Liquid - templiidikeel
• YAML - lihtne märgendkeel
• Sublime Text 3 - programmeerija tekstiredaktor
  • GitSavvy - tekstiredaktori Sublime Text 3 ja Giti lõimetis
• asciiFlow

Järeldus. Kahjuks ei saa me läbi ühe töövahendiga. Töövahendite lõimimine on päris suur väljakutse.

7 Viie projekti võrdlus

‘Mis karakteristikud viivad hea dokumentatsioonini?

• projekt 1: dokumentatsiooni kvaliteet üldiselt hea, nõudis tellija suurt tähelepanu
• projekt 2: eraldi kvaliteedikontroll, võimekad ja hoolsad inimesed, dokumentatsiooni kvaliteet ületab ootusi
• projekt 3: rollide ühitamine, eraldi dokumenteerija ja kvaliteedikontroll puudus; dokumentatsiooni kvaliteet mitterahuldav
• projekt 4: agiilne projekt, eraldi dokumenteerimine eraldi inimese poolt
• projekt 5: Eraldi inimene dokumentatsiooni peal, dokumentatsiooni kvaliteet väga hea

8 Hea dokumentatsiooni tellimise saladus

Empiiriline andmestik viib järgmise üldistuseni. Hea dokumentatsiooni tekib siis, kui:

• dokumentatsioonile on eraldi inimene
• täitjal jääb aega dokumentatsiooni tegemiseks