Pierwsze kroki z dokumentacją

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?

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.

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ć.

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.

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?

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ę.

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.