Section author: Vedran Miletić

Upravljanje dokumentacijom računalnih sustava i mreža

Kako sistemaš radi s mnogo različitih skupova usluga na stvarnim i virtualnim strojevima, često u više različitih konfiguracija, potrebno je održavati dokumentaciju koja opisuje specifičnosti instalacije i konfiguracije postojećih sustava.

Tehnološka rješenja

Za održavanje dokumentacije mogu se koristiti programi za obradu teksta kao što su LibreOffice Writer i Microsoft Word. Kako takvi alati imaju vrlo složene i upitno prenosive formate za pohranu podataka, bolja je praksa koristiti neki od wikija ili generatora statičkih web sjedišta zasnovanih na jednostavnim i svima čitljivim formatima označavanja običnog teksta. Bez obzira na wiki ili generator, dva se formata vrlo često koriste:

Za rad s dokumentacijom koristit ćemo reStructuredText (dokumentacija) i Sphinx (dokumentacija).

Stilska pravila

Kod pisanja interne dokumentacije vrijedi slijediti nekoliko pravila.

  • Nije potrebno pisati općenite informacije koje pišu u službenoj dokumentaciji softvera koji se koristi, npr. sve parametre pojedine naredbe ili sve dozvoljene vrijednosti neke varijable u konfiguracijskoj datoteci. Specifične informacije, npr. značenje konfiguracijske naredbe koja se koristi ili razlog za korištenje određene vrijednosti određenog parametra, svakako treba zapisati. Službena dokumentacija će vrlo vjerojatno biti dostupna tijekom čitavog životnog ciklusa softvera.

  • Potrebno je zapisati upute za instalaciju i konfiguraciju preuzete s nekog foruma, bloga, društvene mreže, web sjedišta o tehnologiji ili sl. Moguće je da te stranice prestanu biti dostupne tijekom životnog ciklusa softvera.

    • Specifično, u slučaju da su upute dane u video formatu, dobro ih je prepisati u tekstualni za lakše kasnije pregledavanje.

  • Dobra struktura dokumentacije je opis – naredbe – opis – naredbe – opis – sadržaj (dijela) konfiguracijske datoteke – …, gdje se prvo navede što naredbe ili konfiguracija rade, a zatim ih se napiše kao blok koda da ih se kasnije može lakše pregledavati i kopirati.

  • Zaporke se ne čuvaju u internoj dokumentaciji, već u specifičnim alatima kao što su KeePassXC, KeePass i Bitwarden.

  • Imena domaćina, IP adrese i slični podaci mogu se čuvati u internoj dokumentaciji, ali treba paziti da interna dokumentacija ostane interna. U slučaju da se dijelovi dokumentacije prerađuju za javnu objavu, imena i adrese treba zamijeniti generičkima.

  • Promjene u tekstu treba čuvati u nekom sustavu za upravljanje verzijama.

Dokumentiranje u vježbanju sistemašenja

(Napisano prema 4. epizodi podcasta 2.5 Admins nazvanoj Zooming from pets to cattle, 22. i 23. minuti gdje Allan Jude govori kako postati sistemaš.)

Dokumentiranje je neizostavni dio učenja sistemašenja. Kad učite biti sistemaš, učite kroz rad (instalaciju operacijskih sustava, postavljanje određenih datotečnih sustava na određene medije za pohranu podataka, konfiguriranje određenih mrežnih usluga i sl.) i istovremeno dokumentirate što radite.

Kad ste gotovi, izbrišete sve što ste upravo postavili i po svojoj dokumentaciji ponovite postupak. Ako je postupak savršeno ponovljiv po dokumentaciji koju ste napisali bez da morate ručno razmišljati o dodatnim koracima koji ne pišu i gledati ostale izvore informacija, izvrsno. Ako nije, dopunite dokumentaciju i ponovite postupak.