Dokumentuj, do diabła ze wszystkiego.
Ostatnio na Slashdot pojawił się wątek na temat tworzenia dokumentacji, który zainspirował mnie do napisania swoich przemyśleń na temat dokumentacji.
Moje kluczowe punkty to:
Zasada nr 1: Nigdy nie jest zrobione
Dokumentacja to ciągły wysiłek, który zawsze pozostaje w tyle za produkcją. Zmiany są dokonywane ad hoc, rzeczy są przenoszone, zaprzestane lub wprowadzane do użytku losowo. Dokumentacja nigdy nie nadrobi zaległości.
Musisz sprzedawać ludziom płacącym rachunki za wartość czasu (a więc i pieniędzy) na aktualizację bieżącej dokumentacji. Często te rozmowy przebiegają w następujący sposób: „pamiętasz, kiedy musiałem spędzić $ TIME, zastanawiając się, w jaki sposób $ THING zostało zepsute? Cóż, kiedy skończyłem, pojawiła się ta notatka technologiczna opisująca $ THING, dzięki czemu następny facet nie przyjdzie muszę to wszystko rozgryźć. ”
Musisz to zrobić, nawet jeśli nigdy nie skończysz.
Zasada nr 2: Jedyną rzeczą gorszą niż brak dokumentacji jest niewłaściwa dokumentacja
To bardziej truizm niż zasada. Dokumentacja może uświadomić ci, że coś jest w znanym stanie i że jeśli coś pójdzie nie tak, możesz zacząć od naprawy.
Ważne jest, aby uznać ten problem.
Zasada nr 3: Piszesz dokumentację dla swojego następcy
Szanse stanowią 95% wszystkiego, co robisz w dokumencie, do którego nigdy nie będziesz musiał się odwoływać. Dokumentacja to zbiór mądrości na przyszłość, a nie dla ciebie. Musisz więc założyć, że twoja publiczność niewiele wie lub nic o szczegółach tego, jak rzeczy wyglądają tak, jak są.
I będzie następca. Nie wiem o tobie, ale nie planuję pozostać w tych konkretnych środowiskach do końca życia. Możliwości przychodzą i odchodzą, a kiedy przychodzą, czasem idziesz. Ale życie toczy się za tobą i im płynniejsze możesz uczynić życie swojego następcy tym lepszym. W przeciwnym razie możesz mieć kolekcję byłych klientów, którzy po cichu mówią o tobie niepochlebne rzeczy. Chciałbym powiedzieć, że jest to tych samych 50 facetów pracujących w IT w Ottawie, ponieważ ciągle ich spotkasz. Pomaganie następcy może w przyszłości otworzyć dla ciebie drzwi.
Teraz do pewnego stopnia zawsze pojawia się „winić poprzedniego faceta”, gdy pojawiają się kłopoty. To część biznesu. Zrobiłem to sam. Ale kilkakrotnie, gdy wysadziłem poprzedniego faceta jako jakiegoś kretyna, nauczyłem się inaczej, że naprawdę miał swój wspólny akt i wiedziałem więcej o tym, co się działo w tym czasie.
Zasada 4: „Dlaczego” jest często ważniejsze niż „Jak”
Kiedy patrzymy na system, większość z nas zaczyna myśleć, dlaczego tak do cholery jest? Prawie zawsze istnieją bardzo konkretne powody, dla których dokonano wyboru konfiguracji. W tych okolicznościach „Dlaczego” dyktuje „Jak” i musisz upewnić się, że czytelnik rozumie konkretne problemy, które zostaną rozwiązane podczas badania pozostałości palenia po twoim rozwiązaniu.
Zasada 5: To musi być łatwe, inaczej nie zrobisz tego
Oznacza to, że musisz być bardzo świadomy swoich narzędzi, a także tych, którzy będą z nich korzystać.
Utrzymywanie aktualności musi być łatwe. Jeśli musisz podjąć jakikolwiek wysiłek, znajdziesz usprawiedliwienia, aby uniknąć robienia tego, kiedy najlepiej to zrobić, czyli natychmiast po zmianie.
Jeśli Twoje narzędzia nie są łatwe w użyciu dla innych, nie będą z nich korzystać. Może to być szczególnie paraliżujące w środowisku zespołowym, ponieważ im większa drużyna, tym bardziej prawdopodobne jest, że spotkasz członka zespołu, który nie lubi twojego wyboru narzędzi.
Osobiście lubię wiki dla dokumentów. Problem polega jednak na tym, że wiki nie wymusza na tobie struktury, więc struktura musi być narzucona z zewnątrz. To zawsze prowadzi gdzieś do konfliktu, ponieważ ktoś ma lepszy / inny pomysł.
W niektórych miejscach korzystałem z dokumentów Word i Visio „opublikowanych” do formatu PDF, przy czym „najnowszy” plik PDF uważany jest za autorytatywny. Jest to dobre, ponieważ masz wtedy kolekcję, którą możesz przekazać swojemu pracodawcy / następcy. Pliki PDF, jeśli są odpowiednio datowane, mogą zawierać historyczny zapis tego, co się wydarzyło, chociaż taki, który nie jest łatwy w nawigacji. Szkoda, że nie lubię programu Word ani Visio i musiałem zrozumieć te narzędzia w celu skutecznego komunikowania pomysłów.
Mój obecny pracodawca bawi się pomysłami dokumentów Word w portalu Sharepoint. Musimy tylko zobaczyć, jak daleko się tam dostaniemy