Planowanie i dokumentacja

Skip to content

To jest tekst przetłumaczony maszynowo, który może zawierać błędy!

Dobra dokumentacja to różnica między pamiętaniem, jak coś działa, a staniem w miejscu o 23:00 w niedzielę, ponieważ serwer jest niedostępny i nikt nie pamięta, jak go skonfigurowano. Dokumentacja może nie być najciekawszą częścią operacji IT, ale jest jedną z najważniejszych.

Dlaczego dokumentować?

Przyczyna Wyjaśnienie
Pamięć Nie zapamiętasz wszystkiego za sześć miesięcy, i nie musisz
Współpraca Inni muszą być w stanie zrozumieć, co zrobiłeś, bez pytania cię
Rozwiązywanie problemów Kiedy coś pójdzie nie tak, bezcenne jest wiedzieć, co jest normalne
Odbudowa Jeśli serwer padnie, musisz wiedzieć dokładnie, jak był skonfigurowany
Możliwość weryfikacji Co zostało zmienione, kiedy i przez kogo?

Skriv dokumentasjonen dla “siebie z przyszłości”

Najlepsza zasada: pisz tak, jakbyś tłumaczył to sobie za sześć miesięcy. To gwarantuje, że uwzględnisz wystarczającą ilość szczegółów bez zbytniego komplikowania rzeczy.

Rodzaje dokumentacji w działaniach IT

Mapa sieci

Mapa sieci przedstawia fizyczną i/lub logiczną strukturę sieci. Może to być wszystko, od prostego szkicu po szczegółowy diagram z VLAN-ami, adresami IP i regułami zapory ogniowej.

Dobra mapa sieci powinna zawierać:

  • Wszystkie urządzenia sieciowe (przełączniki, routery, zapora ogniowa, punkty dostępowe)
  • Strukturę VLAN z podsiecią
  • Adresy IP ważnych urządzeń (serwery, brama)
  • Połączenia między urządzeniami

Plan adresacji IP

Plan adresacji IP to przegląd sposobu dystrybucji adresów IP w sieci. Pomaga utrzymać porządek i unikać konfliktów (dwóch urządzeń z tym samym adresem).

Przykład:

VLAN Nazwa Podsieć Brama Zakres DHCP Uwagi
10 Administracja 10.0.10.0/24 10.0.10.1 .100 - .200 Ograniczony dostęp
20 Pracownicy 10.0.20.0/24 10.0.20.1 .100 - .250
30 Uczniowie 10.0.30.0/24 10.0.30.1 .100 - .250 Tylko internet
50 Serwery 10.0.50.0/24 10.0.50.1 Brak (statyczny) Stałe adresy IP

Adresy statyczne:

Adres IP Urządzenie Rola
10.0.50.10 web-01 Nginx
10.0.50.11 db-01 PostgreSQL
10.0.50.12 monitoring-01 Grafana + Loki
10.0.50.20 proxmox Hypervisor

Listy kontrolne

Listy kontrolne zapewniają, że nic nie zostanie pominięte. Są szczególnie przydatne do zadań, które wykonujesz rzadziej, takich jak konfiguracja nowego serwera lub przeprowadzenie przeglądu bezpieczeństwa.

Przykład: Lista kontrolna dla nowego serwera Linux:

  • Zainstaluj system operacyjny (Debian/Ubuntu)
  • Zaktualizuj wszystkie pakiety (sudo apt update && sudo apt upgrade)
  • Utwórz użytkownika z dostępem sudo
  • Wyłącz logowanie root przez SSH
  • Skonfiguruj zaporę ogniową (ufw)
  • Zainstaluj niezbędne oprogramowanie
  • Skonfiguruj kopię zapasową
  • Udokumentuj serwer w planie IP
  • Przetestuj, czy usługa działa

Dokumentacja zmian

Za każdym razem, gdy dokonasz zmiany w środowisku produkcyjnym (serwer, sieć, usługa), powinieneś to udokumentować. Prosty dziennik może wystarczyć:

## Endringslogg

### 2026-04-14 - Oppgradert Nginx
- **Hva:** Oppdatert Nginx fra 1.24 til 1.26
- **Hvorfor:** Aktualizacja zabezpieczeń (CVE-2025-XXXX)
- **Hvem:** Ola
- **Resultat:** OK, ingen nedetid

### 2026-04-10 - Nytt VLAN for IoT
- **Hva:** Opprettet VLAN 40 for IoT-enheter
- **Hvorfor:** Izolacja IoT od reszty sieci
- **Hvem:** Kari
- **Resultat:** OK, alle printere flyttet til VLAN 40

Użyj Gita!

Jeśli piszesz dokumentację w plikach Markdown (zalecane), możesz kontrolować wersje za pomocą Gita. Wtedy automatycznie uzyskasz historię wszystkich zmian i będziesz mógł zobaczyć, kto co zmienił i kiedy.

Dokumentacja operacyjna

Dokumentacja operacyjna opisuje, jak system działa w swoim obecnym stanie:

Co Przykład
Architektura systemu “Uruchamiamy Proxmox z 3 VM: web, db, monitoring”
Informacje o dostępie “SSH przez port 22, tylko z VPN”
Procedury tworzenia kopii zapasowych “Codzienna kopia zapasowa o 02:00 na dysk zewnętrzny”
Dane kontaktowe “W przypadku problemów, skontaktuj się z Olą (admin)”
Kroki odzyskiwania “Restart za pomocą: sudo systemctl restart nginx“

Narzędzia do dokumentacji

Narzędzie Do czego służy Zalety
Markdown Tekst z prostym formatowaniem Lekki, przenośny, działa z Git
draw.io Diagramy i mapy sieciowe Darmowy, wizualny, eksport do obrazu
Obsidian Aplikacja do notatek z Markdown i linkowaniem Dobry do osobistej bazy wiedzy
MkDocs Publikowanie Markdown jako strony internetowej Profesjonalna dokumentacja
Git/GitHub Kontrola wersji dokumentacji Historia, współpraca, kopia zapasowa

Easy Zadanie 1 - Stwórz prostą mapę sieci

Użyj draw.io (bezpłatne) do narysowania sieci domowej lub szkolnej:

  1. Zacznij od połączenia internetowego i routera
  2. Dodaj przełączniki i punkty dostępowe
  3. Narysuj serwery, komputery i inne urządzenia
  4. Zapisz adresy IP, jeśli je znasz

Nie musi być idealnie. Chodzi o to, aby zacząć myśleć wizualnie o sieci.

Easy Zadanie 2 - Stwórz własną listę kontrolną

Pomyśl o czymś, co regularnie robisz z IT (np. konfiguracja nowej maszyny wirtualnej, instalacja środowiska programistycznego lub konfiguracja VS Code). Napisz listę kontrolną dla tego procesu:

  • Jakie są wszystkie kroki?
  • Co najczęściej zapominasz?
  • Czy możesz uprościć niektóre kroki?

Zapisz ją w dokumencie Markdown, aby móc jej użyć następnym razem.

Medium Zadanie 3 - Udokumentuj jedną ze swoich usług

Wybierz usługę, którą skonfigurowałeś (maszynę wirtualną, kontener Docker, serwer WWW) i napisz krótką dokumentację operacyjną:

  • Co robi usługa?
  • Jak ją uruchomić/zatrzymać?
  • Jaki jest adres IP i port?
  • Czy istnieją kopie zapasowe?

Napisz to w Markdown i umieść w repozytorium Git.

Podsumowanie

  • Dokumentacja dla przyszłego Ciebie: Pisz tak, jakbyś wyjaśniał komuś, kto nie wie nic
  • Mapy sieci i plany adresacji IP zapewniają przegląd infrastruktury
  • Listy kontrolne zapewniają, że nic nie zostanie zapomniane podczas powtarzalnych zadań
  • Dzienniki zmian śledzą, co zostało zrobione, kiedy i przez kogo
  • Dokumentacja operacyjna opisuje, jak systemy działają obecnie
  • Używaj Markdown + Git dla prostej, kontrolowanej wersji dokumentacji