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 stvari koje pišu u službenoj dokumentaciji softvera koji se koristi. 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.