Pisanje dokumentacije – shot me slowly

Za vrlo mali broj osoba mogu reći da vole pisati dokumentaciju. I sam sam takav. A shvatio sam i zašto. Trebalo mi je, ali sam shvatio. Najveća muka pisanja dokumentacije mi je bila – početi. Otvorim dokument, onda gledam u njega pola sata jer ne mogu odlučiti od kuda krenuti. Pa dođe neki mail. Pa zatvorim dokument. I ne napišem dokumentaciju.

A onda bi mi zatrebala. A dokument prazan ili nepotpun. I to u najgorim mogućim trenutcima:

1. Kad krene revizija. A revizija prvo što traži je dokumentacija. Ako nije dokumentirano, nije se dogodilo. Koliko god dobro odradio zadatak ako nisam dokumentirao – nisam ga nikada ni napravio. Onda ili brzinsko pisanje dokumentacije, ili nalaz revizije pa opet pisanje dokumentacije koju sam već mogao imati napisanu.
2. Kad sam trebao odraditi neku aktivnost koja se radi, primjerice, samo jednom godišnje. I naravno, zaboravim proceduru. Pa kopam po Internetu. Pa kopam po četrdeset i osam TXT datoteka s bilješkama. Pa panika jer to mora biti danas.
3. Kada se dogodi incident. Efekt je situacija opisana pod brojem 2 pomnoženo puta tri.

Da bi si smanjio stres krenuo sam kreirati jedan jedinstven dokument koji će mi omogućiti da izbjegnem ove situacije. Ali, čemu standardizirati dokumentaciju? Svatko piše na svoj način, u svojoj strukturi, u svom omiljenom alatu. To nosi svoj set problema. Naročito kada se timu priključuje nova osoba. Shvatiti logiku druge osobe vrlo je zahtjevno i dugotrajno. A nije ni rijetko da jedna osoba nema dvije iste strukture. I dok je toj osobi sve savršeno jasno jer godinama radi po tom principu, nekome tko to vidi prvi put predstavlja veliku prepreku. Taj efekt je izvrsno opisan u istraživanju The Curse of Knowledge (možda ga znate pod “Tappers and Listeners”). Preporučujem pročitati članak, izvrstan je.

Struktura dokumenta

Ovaj dokument je nastao kao rezultat kontinuiranog promišljanja što je potrebno dokumentirati. Velik dio je, naravno, i iskustvo u radu i razgovorima s revizijama. Manual se sastoji od sljedećih poglavlja.

Sadržaj

Naravno, na početku dokumenta je Sadržaj. Iako se možda čini nepotrebnim ali kada dokument naraste i kada je potrebno nešto brzo pronaći, poveznice u ovom poglavlju omogućavaju brzi skok na dio dokumenta koji je potreban.

Uvod

Kratak opis sustava, aplikacije tj. rješenja.

Odgovornosti

Popis osoba koje sudjeluju u održavanju sustava ili eskalacijskim koracima. Također, navode se i svi kontakti vanjskih partnera koji pružaju podršku u održavanju sustava.

Arhitektura sustava

U ovom poglavlju opisati fizičku i logičku arhitekturu sustava. Dijagrami i grafovi su i više nego poželjni. Opisati i arhitekturu ovisnosti o drugim sustavima ili sustavima koji ovise o ovom sustavu.

Izvještajni zahtjevi

Ako postoje zahtjevi za izvještajima o radu sustava ili nekom dijelovima sustava, u ovom poglavlju navesti i opisati kako se, pomoću kojih alata i iz kojih podataka kreiraju izvještaji.

Sigurnosne politike

Ako su definirane dodatne i specifične sigurnosne politike, opišite ih u ovom poglavlju.

Prava pristupa

Opišite prava pristupa za krajnje korisnike. Također, ako postoji privilegirani pristup sustavu, opišite kako se i na koji način osigurava privilegiran pristup.

Sigurnosna pohrana podataka

Opisati alate tj. tehnologiju korištenu za izradi sigurnosnih kopija podataka. Specificirati što je uključeno a što isključeno iz sigurnosne pohrane (navesti i razloge isključivanja). Navesti frekvenciju izrade sigurnosnih kopija te metodu: primjerice jednom tjedno puna kopija, dnevno inkrementalna. Jasno specificirati retenciju sigurnosnih kopija, primjerice posljednjih 365 dana ili posljednjih 7 kopija, kako bi se izbjegla pitanja što je moguće vratiti iz sigurnosne kopije.

Nadzor dostupnosti i performansi sustava

Opisati kako se nadzire dostupnost i metrike performansi sustava, primjerice iskorištenost osnovnih parametara kao što je CPU, RAM, itd. Ako je primjenjivo, navesti kanale isporuke alarma (primjerice SMS, WhatsApp, Teams, Mail) te kome se šalju alarmi (osobe i/ili grupe).

Operativni log zapisi

Opisati što se od log zapisa pohranjuje, na koju lokaciju i koliko se čuva. Nije potrebno opisivati standardne log zapise operativnih sustava i infrastrukturnih aplikacija, već ukoliko postoji dodatno logiranje – primjerice log zapisi razvijenih aplikativnih rješenja.

Osiguravanje oporavka sustava

Oporavak sustava nakon katastrofalnog događaja mora biti dokumentirano. To nije procedura koja bi trebala ostati u nečijoj glavi i predmet “tapkanja” po mogućnostima. Opisati egzaktne korake kako oporaviti sustav nakon katastrofalnog događaja.

Ako postoji regulatorna potreba, dokumentirati testove oporavka s evidencijom točnog vremena koje je bilo potrebno za svaki korak.

Automatizacije

Ako su na sustavu razvijene automatizacije, opisati ih. Primjerice kada se pokreću (u određeno vrijeme ili na neki drugi uzrok), što se pokreće, koji su ulazni parametri i rezultati rada.

Operativne procedure

Ukoliko sustav zahtijeva operativan rad djelatnika, opisati te procedure. Tu mogu biti primjerice procedure zamjene certifikata i slično.

Operativno održavanje sustava

Sustav je potrebno održavati primjerice instalacijama novih verzija. U ovom poglavlju opisati procedure te vrste.

Greške u radu sustava i procedure za oporavak

Greške se događaju, neizbježno je. Važno je da se iz grešaka tj. incidenata nauči i da se ne ponavljaju. Da bi izbjegli ponavljanje incidenata bitno je da dokumentiramo incident te kako je ispravljena greška. Ne zanemarujte greške na testnim sustavima, to vam omogućava da izbjegnete tu istu grešku na produkcijskim okruženjima.

Dodatne napomene

Ako postoje dodatne napomene koje ne pripadaju u neko od ranijih poglavlja, ovdje ih raspišite.

Preuzimanje predloška

Predložak dokumenta možete preuzeti ovdje: [download id=”1232″]. Dokument slobodno preuzmite, koristite, dijelite i modificirajte. Ne tražim puno za uzvrat, samo me navedite kao inicijalnog autora ako je moguće :)

Dokument nije fiksan. Ovo je osnovni kostur koje se može nadopunjavati ali ne mijenjati redoslijed i osnovni kostur. Tako je ujedno fleksibilan ali i ujedno jednoznačno strukturiran.

Dok sam pisao ovaj članak, shvatio sam da nedostaje jedan značajan segment – Cloud. S tim ću se uskoro pozabaviti. A do tada, ako imate savjet ili prijedlog što uključiti u Manual pišite u komentare. To će biti v2.0 i uključivati će zahvale svima koji su kontribuirali :)