O co chodzi z niechęcią do dokumentacji w branży?

Wydaje się, że istnieje awersja do pisania nawet najbardziej podstawowej dokumentacji. Nasze projekty README są stosunkowo puste. Dokumenty nie zawierają nawet zaktualizowanych list zależności.

Czy jest coś, czego nie znam w branży, co sprawia, że ​​programiści nie lubią pisać dokumentacji? W razie potrzeby mogę pisać akapity dokumentów, więc dlaczego inni są temu przeciwni?

Co ważniejsze, jak ich przekonać, że pisanie dokumentów pozwoli nam zaoszczędzić czas i frustrację w przyszłości?

Nie sądzę, że warto spekulować na temat motywacji ludzi, którzy nie przyjmują czegoś, co uważasz za dobrą praktykę, lub którzy nadal robią coś, co uważasz za złą praktykę. W tym biznesie osoby należące do jednej lub obu tych kategorii znacznie przewyższą liczbę osób, z którymi spotkasz się oko w oko, więc przestań się szaleć.

Zamiast tego skup się na problemie i możliwych rozwiązaniach.

1. Napisz własną dobrą dokumentację

Może nie być realistyczne oczekiwanie, że wszyscy w zespole skierują swoje wysiłki na rzeczy, które postrzegasz jako problem. Jest to szczególnie ważne, jeśli jesteś względnie nowym członkiem zespołu. Zgaduję, że tak, bo gdybyś był członkiem założycielem zespołu, wydaje się całkiem prawdopodobne, że już wcześniej rozwiązałeś ten problem.

Zamiast tego zastanów się, czy nie dążyć do tego, aby samodzielnie napisać dobrą dokumentację i zachęcić ludzi do korzystania z niej. Na przykład, jeśli ktoś z mojego zespołu zapyta mnie, gdzie jest kod źródłowy Projektu A lub jakiej specjalnej konfiguracji potrzebuje Projekt A, wskazuję mu stronę wiki Projektu A.

Jeśli ktoś zapyta mnie, jak napisać nową implementację fabryki F, aby dostosować coś do klienta C, odpowiadam, że jest to na stronie 10 przewodnika dla programistów.

Większość programistów nie znosi zadawania pytań, które mogłyby sprawić, że wyglądałyby tak, jakby nie mogły „czytać kodu” nawet bardziej niż nienawidzą czytać dokumentacji, więc po wystarczającej liczbie odpowiedzi tego rodzaju, najpierw przejdą do dokumentów.

2. Udowodnij wartość swojej dokumentacji

Upewnij się, że wykorzystujesz każdą okazję, aby wskazać, gdzie dokumentacja potwierdza swoją wartość (lub miałaby, gdyby była używana). Staraj się być subtelny i unikaj „powiedziałem ci tak”, ale mówienie czegoś takiego jest całkowicie uzasadnione

Na przyszłość strona wiki tego projektu zawiera informacje o gałęzi kodu podstawowego, który został utworzony w celu zapewnienia ciągłej obsługi wersji 2.1, więc w przyszłości możemy uniknąć konieczności wykonywania pełnego testu regresji, jeśli sprawdzą osoby, które utrzymują wydane wersje wiki przed sprawdzeniem kodu.

lub

Tak się cieszę, że zapisałem kroki do wykonania Zadania T. Nie obchodzi mnie to, czy nikt inny go nie użyje - już zaoszczędziłem więcej czasu niż to, co napisałem.

3. Uzyskaj zarząd na pokładzie

Po kilku zdarzeniach, w których posiadanie dokumentacji pozwala zaoszczędzić czas i pieniądze, prawdopodobnie zauważysz wyraźną „odwilż” w kierunku dokumentacji. To jest czas na podkreślenie tego, zaczynając uwzględniać czas na dokumentację w swoich szacunkach (chociaż szczerze mówiąc, zwykle aktualizuję / tworzę dokumenty podczas uruchomionych długich procesów, takich jak kompilacje lub zameldowania). Zwłaszcza, jeśli jest to ostatni wynajem, możliwe, że nie zostanie to zakwestionowane, ale zamiast tego będzie postrzegane jako nowa praktyka, którą przyprowadzasz z poprzedniego miejsca pracy (co może być).

Słowo ostrzeżenia: większość szefów nie lubi zmuszać ludzi do robienia czegokolwiek, szczególnie rzeczy niezwiązanych bezpośrednio z rozliczalnym zadaniem, więc nie oczekuj, że to wsparcie będzie miało formę mandatu. Zamiast tego jest bardziej prawdopodobne, że będziesz mógł stosunkowo swobodnie pisać więcej dokumentów.

4. Zachęcaj do dokumentacji, gdy ją zobaczysz

Być może jednym z powodów, dla których ludzie nie piszą dokumentów tak często, jak powinni, jest to, że czują, że nikt ich nie czyta. Więc kiedy zobaczysz coś, co lubisz, pamiętaj, aby przynajmniej wspomnieć, że byłeś zadowolony, że jest dostępny.

Jeśli Twój zespół dokonuje recenzji kodu, jest to czas, w którym możesz wpisać subtelne słowo lub dwa, aby zachęcić do dobrych komentarzy.

Dziękuję za udokumentowanie obejścia błędu B w Framework G. Nie wiedziałem o tym i nie sądzę, żebym mógł zrozumieć, co robiłeś bez tego.

Jeśli masz kogoś w zespole, który jest naprawdę entuzjastycznie nastawiony do dokumentacji, nie szkodzi kultywowaniu tej osoby przez pójście na lunch lub kawę i upewnienie się, że zaoferujesz trochę potwierdzenia, aby przeciwdziałać zniechęceniu, jakie mogą uzyskać od reszty zespołu nie docenia dokumentacji tak bardzo.

Poza tym to naprawdę nie jest twój problem, chyba że zajmujesz stanowisko kierownicze lub kierownicze. Możesz doprowadzić konia do wody, ale nie możesz go pić. Jeśli to nie jest twój koń, możesz nie być szczęśliwy, że jest spragniony, ale wszystko, co możesz zrobić, to wypełnić koryto.

Są dwa główne czynniki w moim doświadczeniu:

Terminy

Większość firm jest tak nastawiona na datę, że kontrola jakości, zadłużenie technologiczne i faktyczny projekt zostały obcięte, aby kierownik projektu nie wyglądał źle lub nie dotarł do absurdalnego, nadmiernie obiecanego terminu klienta. W środowisku, w którym nawet funkcjonalna jakość jest obniżona, długoterminowa inwestycja, taka jak dokumentacja, ma niewielkie szanse.

Zmiana

Stosunkowo nową najlepszą praktyką dla programistów jest odznaczanie komentarzy. Chodzi o to, że przechowywanie informacji w dwóch miejscach (kod [łącznie z testami] i komentarze wokół kodu) prowadzi do dużych kosztów ogólnych w utrzymywaniu ich w synchronizacji z niewielką korzyścią. „Jeśli twój kod jest tak trudny do odczytania, że ​​potrzebujesz komentarzy, czy nie lepiej byłoby poświęcić czas na jego wyczyszczenie?”

Osobiście nie będę nawet patrzeć na komentarze. Kod nie może kłamać.

Dokumentacja podąża tą samą drogą. Dzięki powszechnemu stosowaniu zwinności ludzie potwierdzają, że wymagania zmieniają się regularnie. Przy powszechnym stosowaniu refaktoryzacji organizacja kodu zmieni się dość znacząco. Po co spędzać czas na dokumentowaniu wszystkich rzeczy, które na pewno się zmienią? Kod i testy powinny wykonywać wystarczająco dobrą robotę.

W grę wchodzi wiele czynników:

1. Dobrze napisany kod jest własną dokumentacją. Wszystkie pozostałe rzeczy są jednakowe, lepiej jest napisać wyraźniejszy kod, który mówi sam za siebie, niż więcej dokumentacji. Zrób to, a będziesz musiał zmodyfikować mniej dokumentacji podczas zmiany tego kodu.

2. Pisanie dokumentacji jest prawdopodobnie inną umiejętnością niż pisanie kodu. Niektórzy programiści są w tym lepsi niż inni. Niektóre są znacznie lepsze w pisaniu kodu niż w pisaniu dokumentacji.

3. Dokumentacja powinna być napisana tylko raz , a nie dwa razy (raz w kodzie źródłowym i ponownie w przewodniku programisty). Dlatego mamy takie rzeczy, jak komentarze XML i generatory dokumentacji. Niestety korzystanie z takich narzędzi może być trudniejsze i bardziej kłopotliwe niż pisanie dokumentacji ręcznie, dlatego nie widzisz tych narzędzi powszechnie używanych.

4. Dobra dokumentacja jest czasochłonna i trudna do zrobienia. Wszystkie inne rzeczy są jednakowe, pisanie nowego kodu może mieć większą wartość niż pisanie dokumentacji dla już istniejącego kodu.

5. Kiedy kod się zmienia, musisz również zmienić dokumentację. Im mniej dokumentacji, tym mniej trzeba zmienić.

6. Zresztą nikt nie czyta dokumentacji, więc po co się tym przejmować?

Słoń w pokoju: programiści nie są (niekoniecznie) pisarzami. Nie muszą też koniecznie przekazywać swoich wdrożeń pisarzom technicznym. Drugi słoń w pokoju: autorzy techniczni zazwyczaj nie są w stanie opracować szczegółów przydatnych przyszłym programistom (nawet jeśli programiści raczyliby im to wyjaśnić).

Złożony system może z czasem stać się nieprzenikniony bez odpowiedniej dokumentacji. Kod staje się mniej wartościowy odwrotnie proporcjonalnie do jego sprawdzalności [sic]. Rozwiązany zarząd wynajmuje Inżyniera oprogramowania, który może odczytać kod i dane koncentryczne od programistów, płaci mu według stawki programisty i upoważnia go do dokumentowania i prowadzenia dokumentacji. Ten pisarz może odczytać kod i będzie wiedział, jakie pytania zadać, i w razie potrzeby poda szczegółowe informacje. Podobnie jak masz dział kontroli jakości, masz dział dokumentacji wewnętrznej.

Kod stanie się bardziej wartościowy, ponieważ możesz licencjonować go stronom trzecim (ponieważ on może go zrozumieć), kod można łatwiej poddać audytowi i ulepszyć / przefaktoryzować, będziesz mógł lepiej wykorzystać kod nawet tam, gdzie możesz to łatwo uwzględnij bardziej lekkie wersje swojego oprogramowania, a będziesz mógł łatwiej wprowadzać nowych programistów do projektu, inżynierowie wsparcia pokochają pracę dla Ciebie.

To się nigdy nie wydarzy.

Co ważniejsze, jak ich przekonać, że pisanie dokumentów pozwoli nam zaoszczędzić czas i frustrację w przyszłości?

Czy to robi?

Istnieją dwa rodzaje dokumentacji:

Przydatna dokumentacja

Dokumentuje, jak korzystać z gotowego produktu, interfejsu API, jakie adresy IP lub nazwy adresów URL mają nasze serwery itp. Zasadniczo wszystko, co jest intensywnie używane na co dzień. Błędne informacje zostaną szybko znalezione i zostaną poprawione. Musi być znaleziony łatwy i łatwy do edycji (np. Online Wiki).

Bezużyteczna dokumentacja

Dokumentacja, która często się zmienia, bardzo mało osób jest nią zainteresowanych i nikt nie wie, gdzie ją znaleźć. Podobnie jak obecny stan wdrażanej funkcji. Lub dokumenty wymagań w dokumencie Word ukrytym gdzieś w SVN, zaktualizowanym 3 lata temu. Napisanie tej dokumentacji zajmie trochę czasu, a później okaże się, że jest błędna. Nie możesz polegać na tego rodzaju dokumentacji. To jest bezużyteczne. To marnuje czas.

Programiści nie lubią pisać ani czytać bezużytecznej dokumentacji. Ale jeśli możesz pokazać im dokumentację, która jest przydatna, napiszą ją. Odnieśliśmy spore sukcesy w moim ostatnim projekcie, gdy wprowadziliśmy Wiki, w której moglibyśmy często wpisywać wszystkie potrzebne informacje.

Powiedziałbym, że głównym powodem jest brak woli i niezrozumienie funkcji dokumentacji. Należy wziąć pod uwagę szereg klas dokumentacji:

Dokumentacja produktu / wydania

To wszystko, co pasuje do Twojego „gotowego” produktu. To nie tylko podręczniki, to CZYTNIKI, dzienniki zmian, instrukcje i tym podobne. Teoretycznie można uniknąć pisania ich, ale w efekcie powstaje produkt, którego ludzie nie chcą używać, lub obciążenie, które jest niepotrzebnie drogie.

Dokumentacja API

To opisuje coś, co powinno być względnie statyczne. Ponieważ wielu konsumentów może kodować do twojego API, powinien być wystarczająco stabilny, aby niektóre prozy opisujące jak go używać miały wartość. Opisanie obsługiwanych parametrów, wartości zwracanej i błędów, które mogą zostać zgłoszone, pozwoli innym użytkownikom zrozumieć interfejs API na odpowiednim poziomie abstrakcji - interfejs ( nie implementacja).

Komentarze do kodu

Wydaje się, że w tej chwili zmienia się opinia branży na temat komentarzy. Kiedy zacząłem profesjonalnie kodować, komentarze były niezbędnym warunkiem pisania kodu. Teraz moda polega na pisaniu tak przejrzystego kodu, że komentarze nie są konieczne. Zaryzykuję przypuszczenie, że jest to częściowo spowodowane faktem, że wiele współczesnych języków jest pisanych na znacznie wyższym poziomie i łatwiej jest napisać czytelny kod w Javie, JavaScript, Ruby itp. Niż w asemblerze , C, FORTRAN itp. Tak więc komentarze miały znacznie większą wartość.

Nadal uważam, że w komentarzach opisujących intencję sekcji kodu znajduje się wartość lub kilka szczegółów na temat tego, dlaczego określony algorytm został wybrany zamiast bardziej oczywistego (aby uniknąć nadgorliwych refaktoryzujących potworów z „naprawiania” kodu, który nie ” faktycznie trzeba to naprawić).

Niestety, w decyzjach programistów o nieudokumentowaniu jest wiele samolubstwa, racjonalizacji i złudzeń. Rzeczywistość jest taka, że ​​podobnie jak kod, podstawowymi odbiorcami dokumentacji są inni ludzie. Tak więc decyzje o napisaniu (lub nie napisaniu) dokumentacji na dowolnym poziomie należy podjąć na poziomie zespołu. W przypadku wyższych poziomów abstrakcji sensowniejsze może być posiadanie kogoś innego niż programistów. Jeśli chodzi o dokumentację na poziomie komentarzy, osiągnięcie porozumienia w sprawie celu i intencji komentarzy powinno być uzgodnione wspólnie, szczególnie w zespołach o mieszanych umiejętnościach i doświadczeniu. Nie jest dobrze mieć starszych programistów piszących kod, do którego młodsi programiści nie mogą podejść. Pewna dobrze umiejscowiona i dobrze napisana dokumentacja może pozwolić zespołowi działać znacznie efektywniej

Oto moje dwa centy.

1. Manifest Agile stwierdza „Działające oprogramowanie w oparciu o obszerną dokumentację” i nie wszyscy czytają dalej, aby dotrzeć do „Oznacza to, że chociaż elementy po prawej stronie mają wartość, bardziej cenimy te po lewej”.

2. Niestety jest to powszechne w https://en.wikipedia.org/wiki/Code_and_fix i dokumentacja nie działa z tym modelem (synchronizuje się).

3. Branża tworzenia oprogramowania nie jest dobrze regulowana. Nie ma prawnego wymogu pisania dokumentacji.

4. Kod samodokumentujący to aktualny trend.

Powiedziawszy to, myślę, że jest tam dużo dobrej dokumentacji.

Dokumentacja wymaga czasu i podejrzewam, że wielu programistów miało zbyt wiele wtyczek z dokumentacją, która była gorsza niż bezużyteczna. Wpadają na pomysł, że nie tylko dokumentowanie sprawi im kłopoty ze strony swojego menedżera (tego samego faceta, który ciągle wycina część harmonogramu kontroli jakości), ale nie pomoże to nikomu, łącznie z nimi.

Każda na wpół przyzwoita dokumentacja to inwestycja w przyszłość. Jeśli nie zależy ci na przyszłości (ponieważ nie myślisz poza kolejną wypłatą lub myślisz, że to nie będzie twój problem), to myśl o zrobieniu dokumentacji jest wyjątkowo bolesna.

Wiele innych odpowiedzi wskazuje na to, że istnieją co najmniej dwa rodzaje dokumentacji: jeden zestaw dla innych programistów i inny zestaw dla użytkowników końcowych. W zależności od środowiska może być potrzebna dodatkowa dokumentacja dla administratorów systemu, instalatorów i personelu działu pomocy technicznej. Każda grupa docelowa ma inne potrzeby i poziomy zrozumienia.

Rozważmy (stereo-) typowego programistę: jest programistą z wyboru. Wybrał karierę poza zasięgiem opinii publicznej i spędza długie godziny za klawiaturą komunikując się przede wszystkim ze sobą. Proces dokumentacji jest formą komunikacji, a zestaw umiejętności wymaganych do tworzenia dobrej dokumentacji jest przeciwny do umiejętności wymaganych do tworzenia dobrego kodu.

Dobry autor dokumentacji może komunikować się w wielu językach: języku użytkowników, języku zarządzania, języku personelu pomocniczego, języku programistów. Zadaniem autora dokumentacji jest zrozumienie, co komunikuje się programista i przetłumaczenie go na formę zrozumiałą dla wszystkich innych grup.

Gdy spodziewasz się, że koderzy rozwiną umiejętności niezbędne do tego, aby stać się dobrymi komunikatorami (pisemnymi lub innymi), ilość czasu poświęcanego na doskonalenie podstawowego zestawu umiejętności (kodowanie!) Zmniejsza się. Im dalej od strefy komfortu (koduje i komunikuje się z innymi programistami), tym więcej czasu i energii będzie potrzebnych, aby dobrze wykonać zadanie. Można zasadnie oczekiwać, że profesjonalny programista będzie chciał skupić się przede wszystkim na swoich kluczowych kompetencjach, kosztem wszystkich innych.

Z tego powodu dokumentację (z wyjątkiem komentarzy kodu wbudowanego) najlepiej pozostawić komunikatorom, a nie programistom.

Czytanie kodu pokazuje, jak to działa. Nie może wyjaśnić, dlaczego : potrzebujesz komentarzy.

Czytanie kodu pokazuje nazwę metody i typy parametrów. Nie może wyjaśnić semantyki ani dokładnej intencji autora: potrzebujesz komentarzy.

Komentarze nie zastępują czytania kodu, lecz go dodają.

Dokumentacja nie jest wykonywana tak jak kod. W rezultacie często nie ma skutecznych pętli informacji zwrotnej, aby zweryfikować, czy dokumentacja jest na miejscu i jest kompletna. Z tego samego powodu komentarze kodu mają tendencję do gnicia.

Donald Knuth promował programowanie literackie jako sposób na poprawę jakości oprogramowania, efektywne pisanie dokumentacji z kodem. Widziałem kilka projektów, które dość skutecznie wykorzystały to podejście.

Osobiście staram się trzymać nowoczesnego trendu utrzymywania publicznego interfejsu API twojego kodu tak, aby był jak najbardziej czytelny, a także używania testów jednostkowych do dokumentowania wykorzystania przez innych programistów. Myślę, że jest to część większego pomysłu posiadania interfejsu API w formie, którą można eksplorować i odkrywać. Myślę, że to podejście jest częścią tego, co HATEOAS stara się osiągnąć dzięki usługom internetowym.

Drobna uwaga, ale wydaje się ważna w przypadku niektórych programistów, którzy piszą nieprzyzwoicie małą dokumentację: nie potrafią pisać. Jeśli masz jakieś przybliżenie systemu 10 palców, zwykle piszesz więcej dokumentacji tylko dlatego, że jest to łatwe. Ale jeśli utkniesz z polowaniem i dziobaniem, jesteś zagubiony. Gdybym był odpowiedzialny za zatrudnienie, sprawdziłbym to.

Ludzie, którzy nie lubią czytać dokumentacji, nie lubią pisać dokumentacji. Wielu programistów zrobi wszystko, aby uniknąć dokładnego przeczytania dokumentu.

Nie skupiaj się na pisaniu, skup się na czytaniu. Kiedy programiści czytają dokumentację i przyswajają z niej rzeczy, zobaczą wartość i będą o wiele bardziej skłonni do pisania niektórych.

Kiedy rozpocząłem swoją obecną pracę i przejąłem projekt sprzętu + oprogramowania od osób, które wcześniej nad nim pracowały, dostałem dokument zawierający około stu stronicowych słów opisujący system. Produkcja musiała zająć kilka dni. Spojrzałem na to może dwa razy. Mimo ogromnej ilości informacji rzadko odpowiadał na rzeczywiste pytania, jakie miałem na temat systemu, a nawet gdy tak było, szybsze było spojrzenie na kod.

Po wystarczającej ilości takich doświadczeń zaczynasz zastanawiać się, po co zawracać sobie głowę? Po co spędzać czas na odpowiadaniu na pytania, których ludzie nigdy nie zadawali? Zaczynasz zdawać sobie sprawę, jak naprawdę trudno jest przewidzieć, jakich informacji ludzie będą szukać w dokumentacji; jest nieuchronnie wypełniona faktami, które okazują się bezużyteczne, niejasne lub oczywiste, i brakuje im odpowiedzi na najbardziej palące pytania. Pamiętaj, że tworzenie użytecznej dokumentacji jest wysiłkiem w przewidywaniu ludzkich zachowań. Tak jak mało prawdopodobne jest, że projekt interfejsu użytkownika odniesie sukces, zanim przejdzie wiele iteracji testowania i debugowania, tak naiwnie jest myśleć, że można napisać użyteczną dokumentację opartą tylko na oczekiwaniach dotyczących interpretacji systemu przez ludzi i tego, co rolę, jaką odgrywa dokumentacja i jej język w tej interpretacji.

Wydaje mi się, że większość presji na pisanie dokumentacji wynika z faktu, że jest to nieprzyjemny obowiązek i ludzie lubią się wzajemnie winić, wykonując nieprzyjemne prace domowe („Nie zjadłeś swojego filboida!”).

JEDNAK

Nie sądzę, aby dokumentacja była pod każdym względem beznadziejna. Myślę, że jest to beznadziejne przede wszystkim, gdy ludzie patrzą na dokumentację jako dodatkowe obciążenie, które musi zostać spełnione przed zakończeniem pracy, jako ostatnia odrobina prac porządkowych, które należy przyspieszyć, i jako pole do sprawdzenia. Dokumentacja jest czymś, co powinieneś przeanalizować w aspektach swojego dnia, które zawsze robisz. Myślę, że e-mail jest szczególnie dobrym sposobem na tworzenie dokumentacji. Po dodaniu nowej funkcji napisz kilku osobom szybki e-mail z informacją, co to jest. Podczas rysowania nowego schematu wygeneruj plik PDF i wyślij go do wszystkich osób, które mogą być zainteresowane. Zalety poczty elektronicznej to:

1. Ludzie zwykle sprawdzają pocztę e-mail, podczas gdy nikt nie przegląda folderu o nazwie „doc”.

2. Wiadomość e-mail istnieje w kontekście, w otoczeniu innych wiadomości e-mail omawiających funkcję i powiązane funkcje oraz wszystko inne, co działo się w tym czasie.

3. Wiadomość e-mail jest krótka, skoncentrowana i ma temat.

4. E-mail pozwala osobom, które chcą zadawać pytania od razu,

5. E-mail jest wysoce przeszukiwalny, ponieważ ludzie używają go do wszystkiego, a klienci poczty znacznie się rozwinęli przez lata.

6. Jeśli jest w wiadomości e-mail, co najmniej jedna inna osoba wie, gdzie go znaleźć.

Teoretycznie powinno się wydawać, że komentarze w kodzie powinny być również „aspektami twojego dnia, które i tak zawsze robisz”, ale szczerze mówiąc, nigdy nie czytam komentarzy w kodzie. Nie jestem pewien, dlaczego, ale po prostu nie są bardzo pomocne, może dlatego, że brakuje kontekstu, który rozwiązuje e-mail.