Pierwsze kroki z dokumentacją

21

Nie robiliśmy żadnej dokumentacji w moim miejscu pracy. Jestem całkowicie nowy i proszę o wskazówki na początek.

Mam parę pytań:

  • Jakie są niezbędne dokumenty, które administrator systemu powinien napisać i przechowywać? A dlaczego są takie ważne?

  • Jak utrzymujesz synchronizację dokumentacji z systemem? Jak zminimalizować powielanie informacji?

  • Polecane przewodniki, najlepsze praktyki, anty-wzory?

Ciastko Z Kurczaka
źródło
Powiązane: Jak dokumentujesz sieć?
Zoredache,

Odpowiedzi:

15

od 2003 roku dokumentuję wszystko na naszej wewnętrznej wiki.

Serwery

  • specyfikacje sprzętu
  • informacje o gwarancji
  • informacje o sieci
  • i oczywiście zainstalowane oprogramowanie i konfiguracja

Przepływy pracy

np. jak dodać lub usunąć użytkownika i dać mu dostęp do wszystkich odpowiednich usług

Ważne linki

  • link do wszystkich interfejsów internetowych
  • link do monitorowanych adresów URL (nagios, munin, apc-monitoring ...)
  • link do wiki (w wersji drukowanej!)

Instrukcje awaryjne

co zrobić, jeśli serwer intranetowy / internet / serwer WWW / itp. nie działa

Ważny:

Wybierz silnik wiki z łatwym eksportem do pliku PDF!
Nie jest to przydatne, jeśli jesteś na wakacjach, serwer z twoją wiki jest wyłączony i nikt nie wie, co robić, ponieważ twoja dokumentacja jest offline

Spójrz na twiki, docuwiki lub mediawiki.

BTW:

jest wtyczka OpenOffice.org do pisania bezpośrednio na mediawiki - bardzo wygodne.

EDYTOWAĆ:

Miło też zapisać kilka informacji /home/adminuser/maintenance. Odbywa się to szybko i może być bardzo pomocne, jeśli kilku administratorów pracuje na serwerze. na przykład:

2009-06-27 -thorsten-
          running aptitude update && aptitude full-upgrade
          everything seems ok
2009-06-25 -andreas-
          cups-pdf wasn't reachable. restarted cups
2009-06-23 -thorsten-
          deleted old log under /var/log/squid
etc.
ThorstenS
źródło
2
+1 za wskazówkę awaryjną, jeśli wiki nie działa.
Manuel Faux
Co to jest OOo? Wygląda jak OpenOffice, ale nie mogę zrozumieć ostatniego „o”. Gdybyś mógł nazwać wtyczkę, byłoby świetnie.
Daniel C. Sobral,
3
tak, OOo to OpenOffice.org ;-) Rozszerzenie: extensions.services.openoffice.org/de/project/wikipublisher
ThorstenS
13

Chociaż zdajesz sobie sprawę, że chociaż wszyscy chcą (i potrzebują) dokumentacji, musisz również zdawać sobie sprawę, że nikt nie ma czasu na czytanie i studiowanie tego.

Nie pisz więc dokumentacji, którą należy przestudiować - zamiast tego ustrukturyzuj swoją dokumentację w taki sposób, aby ktoś mógł szybko znaleźć potrzebne informacje, kiedy będą ich potrzebować - co może się zdarzyć, gdy system jest wyłączony, a CTO jest oddychanie po szyi.

Mając to na uwadze, kilka sugestii ...

  • Unikaj dużych bloków tekstu
  • Listy wypunktowane są twoim przyjacielem
  • Jasny schemat jest złoty
  • Powtarzanie to dobry pomysł (1)
  • Ułatw aktualizację i rozszerzenie

(1) Nie twórz jednego źródła prawdy i nie zmuszaj ludzi do jej wytropienia. Im ważniejszy jest ten pomysł, tym bardziej powinieneś go powtarzać.

Bevan
źródło
2
Jednak z więcej niż jednym źródłem dokumentacji masz więcej niż jedno miejsce, które wymaga aktualizacji, jeśli stanie się nieaktualne i trzeba je zmienić. Dobrym sposobem na obejście tego (jeśli masz wiki lub coś podobnego) jest próba stworzenia jednego prawdziwego źródła prawdy i linkowania do niej z tylu miejsc, ile potrzeba.
Mark
W pewnym stopniu zgadzam się - linki i odsyłacze mogą być naprawdę bardzo przydatne. Istnieje jednak kompromis - w projektowaniu baz danych często zdenormalizowane są tabele w celu ułatwienia raportowania. Myślę, że takie samo podejście jest istotne tutaj - aby zużycie dokumentacji łatwiejsze, powtarzając kluczowe fakty mogą być cenne.
Bevan
dobrze jest rozpowszechniać zasady na szeroką skalę, ale dla takich rzeczy jak adresy IP, hasła, zarządzanie konfiguracją scentralizowane pojedyncze autorytatywne źródło danych, z odpowiednimi kopiami zapasowymi jest kluczem do rozsądnego administrowania.
Tom H
Zgodziłbym się - o ile jest on zarówno dobrze znany, jak i łatwo dostępny - jedno autorytatywne tajne źródło jest zbyt powszechnym antypatternem.
Bevan
Gorąco nie zgadzam się z powtórzeniem, ponieważ jedno zostanie zaktualizowane, a inne nie. Lub będą niespójnie aktualizowane. Zamiast tego ważniejsze dokumenty powinny być łatwiej łączone .
gWaldo,
5

Niezbędne dokumenty:

  • Dokumentacja serwera - specyfikacje / układy dysków / zainstalowane oprogramowanie / cokolwiek wartego uwagi
  • Wspólne procedury - wszystko, co jest robione, co nie jest „trywialne”, powinno mieć udokumentowaną procedurę, szczególnie jeśli jest to coś, czego wcześniej nie robiono.

Synchronizacja dokumentacji może być w zasadzie sprawą „napraw to, jak widzisz błędy”. Wraz z tym musi przyjść świadomość, że dokumentacja może i będzie nieaktualna, i że nie należy jej ślepo śledzić bez uwzględnienia tego. Dokumentacja ma pomóc administratorowi w zadaniach, a nie krok po kroku zestaw zasad, które zastępują krytyczne myślenie.

Minimalizowanie duplikacji - użycie czegoś takiego jak wiki, w którym możesz połączyć dokumentację razem, może w tym pomóc, zamiast powtarzania informacji, po prostu link do niej. Problem polega na tym, że osoba pisząca dokumentację musi wiedzieć, że informacje, które zamierzają powielić, już istnieją. Zazwyczaj jest to kwestia dobrej organizacji.

znak
źródło
4

Przekonałem się, że utworzenie szablonu jest dużą pomocą. W moim przypadku jest to szablon programu Word, ale używaj tego, co ci odpowiada. Utwórz plik szkieletu wraz z polem spisu treści i sekcjami zgodnie z potrzebami. Gdy użyjesz go kilka razy i dokonasz drobnych poprawek, będziesz szybciej tworzyć nowe dokumenty. Spójność formatu będzie bardzo pomocna, zarówno przy tworzeniu dokumentów, jak i późniejszym użyciu. Dokumentacja musi być przechowywana w logicznym miejscu i logicznej strukturze katalogów.

Osobiście sprzeciwiam się powtarzaniu z tego prostego powodu, że sprawia, że ​​utrzymanie jest niepotrzebnie trudne i czasochłonne. Zamiast powielać dokumenty lub ich części, w stosownych przypadkach twórz odniesienia do innych dokumentów. Jeśli coś się zmieni, nigdy nie powinieneś zmieniać odpowiedniej dokumentacji więcej niż raz lub w więcej niż jednym miejscu, w przeciwnym razie to zrobisz mieć zbiór sprzecznych dokumentów, który nikomu nie pomoże.

Tworząc dokumentację, pamiętaj o tym, do czego ona służy. Ktoś później będzie musiał z niego skorzystać. Czy użyteczne będzie wykonanie pracy bez wcześniejszej wiedzy?

John Gardeniers
źródło
3

Nie bezpośrednia odpowiedź na twoje pytanie, ale wskaźnik we właściwym kierunku:

Uważam, że praktyka administrowania systemem i siecią autorstwa Limoncelli i Hogana (znana również jako Biblia Sysadmin) jest bardzo cenna, ponieważ dotyczy kwestii „najlepszych praktyk”, takich jak dokumentacja. Jeśli jeszcze o tym nie wiesz, koniecznie sprawdź to, ilekroć masz szansę.

Tiberiu Ana
źródło
Drugie wydanie tej książki zawiera rozdział dotyczący dokumentacji. W pokrewnej książce „Zarządzanie czasem dla administratorów systemu” znajduje się rozdział dotyczący dokumentacji, który bardziej koncentruje się na tym, co musisz zrobić, a nie na tym, co musi zrobić Twoja organizacja.
TomOnTime,
0

Dla mnie najważniejsze jest to, aby był łatwy w użyciu. Jeśli trudno będzie zaaranżować, ludzie będą tego unikać. Wybieram wiki Traca jako medium do naszej dokumentacji z następujących powodów:

  • Centralnie położony.

    Więcej niż jedna aktywna kopia dowolnego dokumentu prowadzi do zamieszania. Jeśli możesz skierować wszystkich w to samo miejsce, zarówno autorów, jak i odbiorców, możesz uprościć ten proces.

  • Prosta edycja i formatowanie.

    Tyle czasu marnuje się na ładne szablony Word i zgodne ze stylem ostatniego autora. Jeśli nie podoba ci się to, łatwiej jest edytować w ruchu, a autorzy są bardziej skłonni do tego. Rozdzielaj dowolne elementy za pomocą TracLinks.

  • Historia audytu.

    Ważne jest, aby wiedzieć, kto dokonał zmiany, kiedy i dlaczego. Jeśli możesz powiązać go z biletami żądań zmiany i dziennikami zatwierdzeń konfiguracji, to jeszcze lepiej. Haki zatwierdzania SVN są do tego świetne.

Dan Carley
źródło
Używam również trac do dokumentacji jednego projektu. To, czego naprawdę brakuje, to rodzaj bułki tartej na wiki. Mam nadzieję, że już niedługo.
ThorstenS