Dokumentacja jako instrukcja a dokumentacja jako lista kontrolna

W przeszłości rozmawiałem z innymi osobami z mojego działu na temat dokumentacji, w szczególności poziomu szczegółowości i wymagań. Ich zdaniem dokumentacja jest prostą listą kontrolną czynności Y do zrobienia, gdy sprawy X pójdą źle.

Nie zgadzam się. Myślę, że zakłada to, że wszystkie problemy w IT można łatwo sprowadzić do prostych list kontrolnych procedur odzyskiwania. Myślę, że całkowicie ignoruje to złożoność sytuacji, a ponieważ inni ludzie w dziale nie zawsze mają głęboką wiedzę na temat problemu (dlatego piszę dokument - więc mają coś do odniesienia ), że dokumentacja powinna zawierać podstawowe materiały podstawowe, takie jak:

• Cel danego (pod) systemu
• Dlaczego jest skonfigurowany w ten sposób?
• Oczekiwania na zdarzenia, które wystąpią po wdrożeniu ustawień / procedur
• Potencjalne problemy, które mogą powodować niepowodzenia procedur

Jednak jestem raczej przegłosowany, więc moja dokumentacja musi zostać przepisana do postaci, w której jest napisane: „Kroki ABC zastosowane w celu rozwiązania problemu X”. Często słyszę lament, że musi zmieścić się na jednej stronie papieru. Spróbuj wyjaśnić komuś konfigurację list ACL Squid, w tym rozwiązywanie problemów, za pomocą jednostronicowego dokumentu. To tylko jeden z pół tuzina dokumentów, które „czekają na napisanie” jako listy kontrolne odzyskiwania.

Czy zalecana przeze mnie metoda naprawdę idzie za burtę? A może mają rację i powinienem mieć coś przeciwko mojej firmie i napisać prostą listę kontrolną? Obawiam się, że bez względu na to, jak dobrze piszesz listę kontrolną procedur, tak naprawdę to nie rozwiązuje problemu, który wymaga od SysAdmin przemyślenia. Jeśli spędzasz czas na tworzeniu listy kontrolnej procedur odzyskiwania, która ostatecznie nie rozwiązuje problemu (ponieważ istnieją dodatkowe czynniki, które nie są częścią dokumentu z powodu wąskiego zakresu dokumentu ), oraz cel dokument miał na celu uniknięcie ponownego czytania stron podręcznika użytkownika, stron wiki i stron internetowych, dlaczego więc wykonuję te ruchy? Czy po prostu martwię się zbytnio, czy to prawdziwy problem?

EDYTOWAĆ:

Obecnie w dziale nie ma stanowiska pomocy technicznej. Odbiorcami dokumentacji będą inni administratorzy lub szef działu.

Pisząc moje, zawsze zmieniałem się w pisanie dwóch trzech zestawów. Lista kontrolna czynności wykonywanych wraz z DUŻO DŁUŻSZYM dodatkiem na temat architektury systemu, w tym dlaczego rzeczy są robione takimi, jakimi są, prawdopodobnymi punktami krytycznymi po wejściu do Internetu oraz abstrakcyjnymi założeniami projektowymi. następnie lista prawdopodobnych problemów i ich rozwiązania, a następnie dłuższa sekcja z informacjami o tym, jak działa system, dlaczego działa w ten sposób, oraz innymi informacjami przydatnymi do wskazywania ludziom właściwego kierunku, jeśli coś wyjątkowego się stanie.

W mojej ostatniej pracy musieliśmy napisać dokumentację, aby nawet pracownicy działu pomocy technicznej na pierwszym poziomie mogli przywrócić rzeczy. Wymagało to list kontrolnych, które na ogół stały się nieaktualne w ciągu 3 miesięcy od napisania. Usilnie namawiano nas do napisania przewodników dotyczących rozwiązywania problemów, gdy tylko jest to możliwe, ale gdy drzewo awaryjne zawiera więcej niż trzy gałęzie, po prostu nie można napisać tego dokumentu bez streszczenia.

Po opuszczeniu moją ostatnią pracę, zagrał 100 stronie „Jak zrobić moją pracę” podręcznik przed wyjazdem. Zawierał w sobie elementy abstrakcyjne, filozofię projektowania oraz punkty integracji. Ponieważ prawdopodobnie pisałem dla innego sysadmina, który miał mnie zastąpić, skierowałem go na kogoś, kto mógł przyjmować abstrakcyjne pojęcia i zamieniać je w konkretne działania.

Minęło pięć lat i moja opinia na ten temat nieco się zmieniła. Zarówno Dokument jako Podręcznik, jak i Dokument jako Lista Kontrolna mają bardzo cenne miejsca w hierarchii dokumentacji i oba muszą zostać stworzone. Są jednak skierowane do bardzo różnych odbiorców.

Dokument jako lista kontrolna

Rynkiem docelowym dla tego rodzaju dokumentacji są współpracownicy, którzy chcą jak to zrobić. Występują w dwóch rodzajach:

• Współpracownicy, którzy chcą tylko wiedzieć, jak coś zrobić, i nie mają czasu, aby przejrzeć piętnastostronicowy podręcznik i samemu wymyślić kroki.
• Procedury są dość skomplikowane etapami, ale należy je uruchamiać tylko raz na jakiś czas.

Niecierpliwość jest motorem pierwszego rodzaju. Być może twój współpracownik tak naprawdę nie chce wiedzieć, dlaczego wyjście musi zostać przepuszczone przez wyrażenie regularne perla o długości 90 znaków, tylko po to, aby zamknąć bilet. Zdecydowanie dołącz oświadczenie typu „Aby uzyskać szczegółowe wyjaśnienie, dlaczego ten przepływ pracy wygląda tak, kliknij ten link” na liście kontrolnej dla tych, którzy chcą wiedzieć, dlaczego.

Drugi punkt dotyczy procedur, które nie są uruchamiane często, ale zawierają pułapki. Lista kontrolna działa jak mapa, aby uniknąć Pewnego Zagłady, która go po prostu uskrzydla. Jeśli lista kontrolna jest przechowywana w repozytorium dokumentacji, oszczędza to konieczności przeszukiwania wiadomości e-mail w czasie, gdy stary administrator wysłał HOWTO.

Moim zdaniem dobra lista kontrolna-dokumentacja zawiera również sekcje dotyczące możliwych punktów awarii i odpowiedzi na te awarie. To może sprawić, że dokument będzie raczej duży i wywołać odpowiedzi TL; DR u współpracowników, więc uważam, że utworzenie trybów awarii i ich odpowiedzi jako linku z listy kontrolnej, a nie na samej stronie, tworzy niecodzienną listę kontrolną. Obejmuj hipertekstowość.

Dokument jako podręcznik

Rynek docelowy dla tego rodzaju dokumentacji to ludzie, którzy chcą dowiedzieć się więcej o tym, jak działa system. Dokumentacja w stylu „jak to zrobić” powinna być oparta na tej dokumentacji, ale częściej widzę ją jako uzupełnienie dokumentacji w stylu listy kontrolnej, która wspiera kopię decyzji podejmowanych w przepływie pracy.

To jest dokumentacja, w której uwzględniamy takie elementy do żucia, jak:

• Wyjaśnienie, dlaczego jest skonfigurowany w ten sposób.
  • Ta sekcja może obejmować takie nietechniczne kwestie, jak polityka związana z zakupem i instalacją całości.
• Objaśnienie typowych trybów awarii i ich reakcji.
• Wyjaśnienie wszelkich umów o gwarantowanym poziomie usług, zarówno pisemnych, jak i faktycznych.
  • De facto: „jeśli to się nie powiedzie w tygodniu finałowym, jest to problem zrzucania wszystkiego. Jeśli podczas przerwy letniej, wróć do łóżka i poradzisz sobie z tym rano”.
• Określanie celów aktualizacji i refaktoryzacji.
  • Polityka może później być inna, dlaczego nie naprawimy złych pomysłów, które wprowadziliśmy na początku?

Które są bardzo przydatne do uzyskania kompleksowego zrozumienia całego systemu. Nie potrzebujesz kompleksowego zrozumienia, aby wykonywać proste zadania automatyzacji człowieka, potrzebujesz go, aby dowiedzieć się, dlaczego coś zepsuło się tak, jak to miało miejsce, i masz pomysł, jak sprawić, by nie zrobił tego ponownie.

Wspomniał także o dokumentacji odzyskiwania po awarii, która musi być listą kontrolną.

Rozumiem, masz moje współczucie.

Tak, dokumentacja DR musi być jak najbardziej podobna do listy kontrolnej.
Tak, dokumentacja DR jest najbardziej odporna na listy kontrolne ze względu na to, ile sposobów może się zepsuć.

Jeśli twoja lista kontrolna DR wygląda następująco:

1. Zadzwoń do Dustina lub Karen.
2. Wyjaśnij problem.
3. Cofnij się.

Masz problem. To nie jest lista kontrolna, to przyznanie, że odzyskanie tego systemu jest tak złożone, że architekt musi się zorientować. Czasami to wszystko, co możesz zrobić, ale staraj się tego unikać, jeśli to w ogóle możliwe.

Idealnie dokumentacja DR zawiera listy kontrolne procedur dla kilku różnych rzeczy:

• Procedury segregowania, aby dowiedzieć się, co poszło nie tak, co pomoże zidentyfikować ...
• Procedury odzyskiwania dla niektórych przypadków awarii. Które jest obsługiwane przez ...
• Skrypty odzyskiwania napisane z dużym wyprzedzeniem, aby zminimalizować błędy ludzkie podczas odzyskiwania.
• Dokumentacja w stylu ręcznym na temat przypadków awarii, ich przyczyny i ich znaczenia.

Procedury segregowania są czasami całą dokumentacją DR, którą można wykonać dla niektórych systemów. Oznacza to jednak, że wywołanie 4 rano będzie bardziej zrozumiałe, a starszy inżynier przeprowadzający proces odzyskiwania będzie w stanie szybciej dotrzeć do rzeczywistego problemu.

Niektóre przypadki awarii mają proste procedury odzyskiwania. Dokumentuj je. Podczas ich dokumentowania możesz znaleźć przypadki, w których listy poleceń są wprowadzane w określonej kolejności, co jest doskonałym przykładem użycia dla skryptów; może zmienić 96-punktową procedurę odzyskiwania w 20-punktową. Nigdy nie dowiesz się, czy możesz coś napisać, dopóki nie zmapujesz procedury odzyskiwania akcja po akcji.

Dokumentacja w stylu ręcznym dla przypadków awarii jest ostatnim ogranicznikiem rowu, który należy zastosować, gdy nie ma żadnych procedur odzyskiwania lub procedury odzyskiwania nie powiodły się. Zawiera wskazówki Google potrzebne do znalezienia kogoś, kto miał ten problem i co zrobił, aby go naprawić.

Właściwie nie używamy Documentation As-a-Testcase

Biorąc to pod uwagę, mamy pisemną dokumentację, która jest dołączona do dokumentacji jako podręcznika . Mieliśmy listy kontrolne, ale podczas ich rozwoju okazało się, że są one podatne na błędy i naprawdę zawodzą w całym systemie.

Mamy jednak zainstalowaną rodzaj „Listy kontrolnej dokumentacji”, czyli - jak wspomniano powyżej - intensywnie monitorujemy nasze usługi. Jest takie powiedzenie:

Jeśli go nie monitorujesz, nie zarządzasz nim

To jest całkowicie prawdą, ale kolejna powinna być:

Jeśli go nie monitorujesz, nie dokumentujesz go

Ilekroć musimy migrować usługi, po prostu utrzymujemy „Grupę usług”, „Grupę hosta”, cokolwiek ma zastosowanie (używamy Nagios, jak można się domyślić ze słownictwa) otwarte i nie jest migrowane, dopóki jest jeden czerwony punkt w dowolnej usłudze.

Testy zapewniają znacznie lepszą listę kontrolną niż jakakolwiek inna odręczna lista kontrolna. W rzeczywistości jest to samo dokumentowanie, gdy tylko pojawi się jakaś awaria, która nie była monitorowana, ale test zostanie przynajmniej dodany do Nagios, dzięki czemu otrzymamy 2 rzeczy za darmo:

• wiemy, kiedy zawodzi
• kolejny punkt na liście kontrolnej

„Prawdziwa” dokumentacja jest przechowywana na Wiki, podając szanse i zakończenia danej usługi lub testu. Jeśli go nie ma, ludzie dodadzą go, gdy tylko będziemy musieli przeprowadzić migrację lub pracować z nią, do tej pory podejście to działało bardzo dobrze.

Również błędna dokumentacja jest opracowywana bardzo szybko, za każdym razem, gdy coś się nie powiedzie, ludzie zaczynają przeglądać dokumentację i próbują rozwiązać problem z zawartymi w niej instrukcjami, jeśli to źle, po prostu zaktualizuj ją o swoje ustalenia.

Pomyśl tylko o błędach, które możesz stworzyć, postępując zgodnie z listą kontrolną i nie instalując żadnych testów, które dadzą ci zielone pole wyboru po ich zastosowaniu. Nie sądzę, że można oddzielić Dokumentację od Monitorowania.

Twoja dokumentacja zależy od docelowych odbiorców.

W przypadku rodzajów pomocy technicznej (poziom 1) właściwa jest lista kontrolna; oczywiście zakłada to, że istnieje wyższy poziom wsparcia przy głębszej wiedzy, którą opisujesz.

Jeśli dokumentacja dotyczy grupy systemów, zawsze popełniam błąd po stronie większej ilości dokumentacji. Wystarczająco trudno jest mieć odpowiednią dokumentację, jeśli ktoś (sam) chce napisać obszerniejsze dokumenty z niezbędnymi informacjami podstawowymi - żadna zdrowa osoba nie powinna przeszkadzać!

Osobiście staram się, aby dokumentacja była jak najprostsza. Zwykle obejmuje:

• Co powinien zrobić [X] (wymagania).
• Jak zbudowano [X] na wysokim poziomie (projekt).
• Dlaczego zaimplementowałem [X] tak, jak to zrobiłem (uwagi dotyczące implementacji).
• Jak implementacja [X] jest niestandardowa (obejścia).
• Typowe problemy z [X] i sposoby ich rozwiązania (problemy).

Tak więc, co prawda, moja sekcja z typowymi problemami prawdopodobnie będzie krótkim opisem tego, co się wydarzyło, oraz punktowymi wskazówkami, jak to naprawić.

Zazwyczaj zakładam pewną wiedzę od czytelnika omawianego systemu (chyba że jest on szczególnie tajemny). Nie mam czasu, aby większość dokumentacji technicznej poziomu 1 lub zarządzania była czytelna - ale wskazówka na poziomie 3 powinna być w porządku.

Myślę, że to oczywiście zależy od tematu. Nie wszystko można sprowadzić do prostej listy kontrolnej i nie wszystko wymaga szczegółowej instrukcji obsługi.

Z pewnością brzmi to tak, jakbyś mówił o wewnętrznej dokumentacji, i z mojego doświadczenia wynika, że ​​nie możesz po prostu podać listy kroków, ponieważ istnieje zbyt duży wybór. Nawet utworzenie konta użytkownika ma pewne opcje (w naszym środowisku), więc nasz dokument „Nowe konto” zawiera listę podstawowych kroków w kolejności, ale dla każdego kroku znajduje się opis tych wariantów.

Z drugiej strony, nigdy nie zajmowaliśmy się pisaniem dużej części dokumentu do „Jak załatać w biurze”, ale nasz bardzo szkicowy dokument również nie był listą kontrolną - wspomniał o konwencji stosowanej dla kolorów kabli, podkreślał że miał do aktualizacji arkusza że wymienione połączenia, a to było o tym.

Teraz, kiedy to napisałem, całkowicie się zgadzam: listy kontrolne krok po kroku po prostu nie pozwolą na wiele procesów.

Zdecydowanie się z tobą zgadzam (na rzecz wyczerpującej dokumentacji) po części dlatego, że jestem przyzwyczajony do posiadania poprzedników, którzy wcale NIE byli zainteresowani dokumentami. Jak powiedziano w powiązanych postach, napisanie go jest dobre nie tylko dla innych, ale pomaga lepiej zrozumieć twoje środowisko i utrwalić je we własnym umyśle. To koniec sam w sobie.

Nawiasem mówiąc, stwierdzam, że wiele błędów wynika z dziwnego przekonania, że ​​gówniana / nieistniejąca dokumentacja = bezpieczeństwo pracy. Takie myślenie wydaje się po prostu nieuczciwe i podejrzane.

Uznanie dla ciebie za zniszczenie status quo.

Dużo dokumentuję, mam nawet listę kontrolną priorytetów dokumentów :-), jednak nie będę dokumentować rzeczy, które można uznać za ogólną wiedzę (tj. Rozsądny dobry opis problemu daje odpowiedź na pierwszej stronie google).

Dla wszystkich zainteresowanych tutaj jest moja lista kontrolna doc prio (działa dla mnie, może nie dla ciebie, komentarze i sugestie są bardzo mile widziane):

1. Stwórz osobisty dziennik / dziennik, w którym zapisujesz wszystko, co zrobiłeś / posiadasz wiedzę
2. Usługi, która usługa jest gdzie, co i dla kogo jest wykonywana (wszelkie umowy SLA? Czy należy je utworzyć?)
3. Serwery, jaki serwer jest gdzie, ile ma lat i kiedy jest napisany
4. Jak wyżej, ale dla urządzeń sieciowych, UPS i tym podobnych
5. Jak wyżej, ale dla wszystkich komputerów użytkowników
6. Układ sieci fizycznej (który kabel idzie gdzie, jak długo i jaka jest zmierzona jakość)
7. Przegląd konfiguracji oprogramowania i licencji dla serwerów
8. Przegląd konfiguracji oprogramowania i licencji dla komputerów użytkowników
9. Przegląd konfiguracji przełączników, routerów i innego dedykowanego sprzętu
10. Umowy i SLA wszystkich stron zewnętrznych, dla których moja usługa jest bezpośrednio zależna (ISP, domena itp.)
11. Skonfiguruj system biletów ze zintegrowaną wiki, aby umieścić w nim wszystkie powyższe rzeczy.
12. Dla każdego incydentu utwórz bilet (nawet jeśli używasz go tylko dla siebie).
13. Utwórz skrypt, który w niedzielę zbiera bilety i grupuje je według rodzaju problemu.
14. W poniedziałek stwórz automatyczne rozwiązanie lub dokument dla użytkownika końcowego dotyczący najczęściej pojawiającego się problemu
15. Jeśli czas na to pozwala, zrób następny.
16. Jeśli nie masz nic więcej do roboty, poszukaj nowej pracy i daj osobie, która zastąpi Ci log ;-)

Lista kontrolna jest w porządku, o ile nie udaje kompletnej dokumentacji. Ostatnie kilka dokumentów, które napisałem, składało się z dwóch części: XYZ dla użytkowników, która zawierała ładne zrzuty ekranu z tego, jak z niego korzystać; i XYZ dla administratorów systemu, w tym sposób jego konfiguracji i dlaczego (być może nawet wymaganie biznesowe, aby istniał), pułapki, których należy unikać, oraz rozdział dotyczący rozwiązywania problemów. Rozwiązywanie problemów to miejsce, w którym spodziewałbym się znaleźć listy kontrolne. Być może napisanie list kontrolnych jako XYZ dla pomocy technicznej może pomóc w zrozumieniu tego.

Teraz czytanie między wierszami, skupianie się tylko na listach kontrolnych, wskazuje mi na brak myślenia „dużego obrazu” i długofalowego planowania, których oczekiwałbym od kogoś, kto: kiedykolwiek udzielał wsparcia technicznego; lub młodszy administrator dopiero zaczynający; lub jest tak zalany pracą, że nie ma czasu o tym myśleć; lub nigdy nie został zmuszony do myślenia o tym; albo zwyczajnie to nie obchodzi. Nie wiem, które z nich, jeśli w ogóle, mają zastosowanie w twoim przypadku.

Jestem dość duża w dokumentacji. Firma, w której pracuję, uważa, że ​​dokumentacja jest ważna, ale niektórzy ludzie w firmie uważają, że nie mają czasu na pisanie dokumentacji. Może to utrudnić życie każdemu oprócz osoby, która to pierwotnie zrobiła.

W przypadku niektórych rzeczy napisałem instrukcje krok po kroku. Możesz nazwać to listą kontrolną, jeśli chcesz, ale tak naprawdę nie jest przeznaczona do fizycznego sprawdzania. Mój styl dokumentacji nazywam „krokiem do przedszkola”. Jest wzorowany na zeszycie ćwiczeń MCSE, które miałem na jeden z egzaminów Windows 2000. Kroki są bardzo szczegółowe, ale użycie pogrubienia / kursywy / kroju pisma ułatwia wybielanie i wybieranie ważnych części, dzięki czemu nie musisz czytać wszystkiego po nauczeniu się tych kroków.

Niektóre rzeczy nie nadają się dobrze do instrukcji krok po kroku, więc staram się dostarczyć jak najwięcej danych konfiguracyjnych, jak mogę. Pewna technicznie skłonna osoba, która skończy na utrzymaniu drogi, będzie miała lepsze pojęcie o tym, z czym ma do czynienia, i miejmy nadzieję, że ułatwi jej życie, gdy coś pójdzie nie tak.