Dokumentacja poniżająca - jak sobie z tym poradzić?

Ważne : nie mamy żadnych problemów z dokumentacją kodu źródłowego . Należy to do regularnego audytu kodu i jest na bieżąco aktualizowane. Nasz problem dotyczy dokumentacji programistów (lub „zewnętrznych”, jeśli chcesz), małych blogowych wskazówek od programistów do programistów, które zwykle są pisane, często pozostawione.

Używamy systemu typu wiki do tworzenia dokumentacji dla programistów - artykułów napisanych przez programistów dla programistów opisujących nieco więcej szczegółów, jak działa dany fragment kodu. Te strony wiki zazwyczaj obejmują:

• motywacje związane z decyzjami projektowymi dotyczącymi części API (na przykład, zrobiliśmy to brzydkie rzeczy, ponieważ ta konkretna biblioteka innej firmy chce, aby rzeczy były robione w ten sposób, ponieważ ta inna biblioteka ..., ponieważ ...)
• wyjaśnienie, w jaki sposób radzimy sobie z poszczególnymi typowymi zadaniami (na przykład wyświetlanie trywialnego wyskakującego okienka, które musi odwoływać się do odpowiednich stylów aplikacji, zarejestrować się w komponencie rejestru i zaimplementować jakiś interfejs, aby być automatycznie „skanowane” przez inny komponent)
• dobre praktyki (jakkolwiek subiektywne, tak naprawdę to spisujemy)
• konfiguracja środowiska, wymagane narzędzia i konfiguracja

Ogólnie rzecz biorąc, przede wszystkim rzeczy związane z pisaniem kodu, które nie pasują do zwykłej dokumentacji kodu ze względu na jego rozmiar i charakter postu na blogu / artykuł.

Problem

O ile wprowadzenie tego systemu wydawało się dobrym pomysłem kilka miesięcy temu, obecnie czuję, że powoduje więcej problemów niż rozwiązuje. Na przykład:

• ludzie zrobić artykuły zapisu ... ale gdy kod zmieniony, zmiana następuje rzadko wiki
• wiele artykułów na zarysowania , napisanych przez kogoś w pośpiechu i tak zostawionych
• mimo że zamówienie na artykuł zwykle pochodzi od kierownika projektu, rzadko jest ono weryfikowane pod kątem poprawności / składu - co czasami skutkuje niską jakością

Zwykła degradacja. Kod został zmieniony, wiki pozostaje bez zmian. Następnym razem, gdy ktoś szuka informacji, zwykle znajduje kilka przestarzałych rzeczy niskiej jakości - i zastanawia się, co się dzieje, czy rzeczy, które znalazł, są dokładne, a nawet gorzej. I to, co miało pomóc, kończy się odwrotnością.

W tej chwili wydaje się, że ludzie zdają sobie sprawę z problemu, w tym kierownika projektu, ale najwyraźniej nikt nie wydaje się, że miałby z tym coś wspólnego (lub ma coś ciekawszego do zrobienia).

Początkowo myślałem, aby rzucić to wszystko w zapomnienie (po tym, jak kilka razy z rzędu ugryzły mnie przestarzałe „wskazówki”), ale przypuszczam, że może to być zbyt ekstremalne. Warto zwrócić uwagę na niektóre informacje i czasem je przeczytać, ale problem pozostaje ten sam: jak radzisz sobie z ich „aktualnością” ? Czy w jakiś sposób powiązano go z kodem źródłowym (więc po sprawdzeniu zaktualizowanej wersji pliku autor artykułu zostaje powiadomiony o konieczności zmiany kodu / artykułu)? Czy wyznaczona osoba „czuwa” nad codziennymi podstawami? Czy regularne porządki?

Wygląda na to, że dokumentujesz zbyt wiele ciekawostek na wiki.

Dokumentuj bloki kodu i metody w kodzie . Postaraj się, aby kod sam się dokumentował, abyś nie musiał komentować. Pisanie testów jednostkowych również może pomóc.

Dokumentuj decyzje projektowe i architekturę z większą szczegółowością na wiki, aby wiki nie musiała często zmieniać ani zajmować dużo pracy. Jeśli wiele osób w twoim zespole zna już architekturę, a zespół nie rozwija się gwałtownie, być może nie ma żadnego uzasadnienia dla udokumentowania ich w ogóle, bezpośrednia wymiana wiedzy jest często najlepszym rozwiązaniem.

Natychmiast przepisuj lub usuń nieaktualne informacje , takie jak martwy kod, im dłużej pozostaje ono tym trudniejsze do wykrycia i tym więcej się gromadzi. Jeśli nie masz czasu, po prostu go usuń i zaznacz artykuł jako wymagający przeróbki, spowalnia on i jest przechowywany w kontroli wersji.

Dokumentuj procedury, automatyzując je w skrypcie lub pliku instalacyjnym. W przeciwnym razie przechowuj je na wiki, ale za każdym razem, gdy ktoś korzysta z procedury z wiki, powiedz mu, aby spróbował ulepszyć artykuł lub zautomatyzować część procesu.

Artykuły na blogach należą do blogów . Jeśli ludzie chcą dzielić się swoimi osobistymi opiniami i poradami, stwórz blog firmowy. Prawdopodobnie nie chcą, aby ich artykuły były modyfikowane i nikt i tak ich nie zmodyfikuje, więc nie pozwól im zaśmiecać wiki.

Dokumentacja powinna być traktowana jako produkt dostarczalny, a zatem podlegać zasadom identyfikowalności i akceptacji, a także zapewnić odpowiednią ilość czasu na opracowanie.

Często zdarza się, że ludzie „oczekują” dokumentacji oprogramowania, jeśli nie jest to dane.

Radykalny, ale skuteczny. Jeśli ktoś napisał nowy moduł, ale go nie udokumentował - otwórz ponownie narzędzie do śledzenia problemów, a jeśli to konieczne, nie wysyłaj całego nieudokumentowanego kodu źródłowego. Jeśli pozwolisz programistom traktować dokumentację kodu źródłowego jako zło konieczne, otrzymasz fragmentaryczne i nieaktualne skrawki dokumentacji.

W moim ostatnim projekcie staramy się przynajmniej śledzić wszystkie niezbędne biblioteki stron trzecich. Jeśli ktoś wprowadzi nową bibliotekę, ale nie jest to udokumentowane - wycofujemy rozwiązanie do momentu wprowadzenia dokumentacji. Bez tak radykalnego podejścia nastąpiłby chaos. Na przykład niedoświadczony programista może skorzystać z biblioteki, której licencja jest w konflikcie z licencją naszego oprogramowania.

Jeśli coś szybko się zmienia, nie należy tego utrzymywać poza kodem.

motywy decyzji projektowych dla części API

Jest to szczególnie ważne, aby trzymać się blisko kodu. Jak w, w tym samym pliku źródłowym. W ten sposób nieco trudniej będzie zignorować za każdym razem, gdy ktoś dotknie pliku, i poprosi o mniej zgłoszeń do TheDailyWTF przez osoby, które nie wiedzą, że istnieje zewnętrzna dokumentacja.

Zwykła degradacja. Kod został zmieniony, wiki pozostaje bez zmian.

W tym miejscu bardzo przydatna staje się „dokumentacja wykonywalna” - testy jednostkowe. Jeśli kod się zmieni, a testy nie zmienią się wraz z nim, kompilacja się zepsuje. Oczywiście pisanie testów jako dokumentacji wymaga pewnych umiejętności. Ale tak samo dzieje się z pisaniem (dobrej) dokumentacji zewnętrznej.

Dobrym sposobem na poradzenie sobie z problemem jest włączenie go do procesu. Jeśli masz śledzenie kodu do / odnośników do odpowiednich stron na wiki, programista może łatwo dowiedzieć się, co może wymagać aktualizacji. Ponadto spraw, aby recenzenci byli odpowiedzialni za sprawdzenie kodu za upewnienie się, że wiki jest aktualne (w odniesieniu do aktualizacji).

Innym sposobem dodania go jako części procesu - ponieważ używasz modelu zwinnego, który jest częścią procesu planowania iteracji, może być aktualizacja planowanych zmian na wiki. Wiki służy wtedy jako zasób „tak powinno działać”.

Jeśli używasz języka .net, spójrz na ( Sandcastle ), który pobiera dokumentację XML (/// w C #) i konwertuje ją na format pomocy MSDN.

Format zawiera opis, komentarze i ma możliwość włączenia próbek kodu, a także niektórych innych funkcji. Możesz wyprowadzać dane do formatów .CHM, .HsX, .MSCH i HTML / ASP.NET. Rzeczywisty projekt zostanie dodany do twojego rozwiązania i zbudowany na serwerze kompilacji. Zrobiliśmy to i wdrażamy na stronie internetowej każdą wersję, a klienci uwielbiają ją, ponieważ dokumentacja jest istotna dla wersji i stale aktualizowana.

Możesz także określić, co należy uwzględnić w dokumentacji. Obecnie mamy 2 projekty: jeden dla zewnętrznych konsumentów, który zawiera tylko umowy i odpowiednie elementy (klasy, wyliczenia itp.), A drugi dla wewnętrznych programistów, który zawiera wszystko w interfejsie API, w tym elementy oznaczone jako prywatne i wewnętrzne.

Stała się jedyną używaną przez nas dokumentacją, ponieważ motywacje i dziwactwa związane z korzystaniem z API można znaleźć w sekcji Komentarze w dokumentacji. Proces działa dobrze tam, gdzie pracuję.

Skoncentrowałbym się na dwóch obszarach: 1) Kod. 2) Notatki i dokument bez kodu.

1) Kod.

Postaraj się, aby była to samo dokumentacja. W przeszłości stwierdziłem, że często było to zalecane, ale rzadko wyjaśniane, więc ...

Zamiast tego rodzaju pseudo kodu:

# Routine by mdd on 7/25/2012
# processes cars for sale
a=0
col = Car.all
Collection.loop |a|
 if a.stat = 'fs' then 
   a+= a.value    
   call easo 
  endif
end

Zrób kod, który wygląda mniej więcej tak:

accumulating_potential_sale_revenue = 0
cars_to_check = Car.all
cars_to_check.loop |one_car|
  if one_car.sell_status == 'for_sale'
    accumulating_potential_sale_revenue+= one_car.sale_price
    call email_about_special_offer(car)
  endif
end

Użyj kontroli źródła, aby śledzić informacje „kto co zrobił, kiedy”.

2) Brak kodu

Użyj formatu wiki i Markdown, aby zachować te informacje. Niech to będzie częścią pracy. Opublikuj to, opublikuj i bloguj. Ustaw standardowe cotygodniowe lub comiesięczne spotkanie, aby przejrzeć stare i nowe rzeczy. Zrób z tego mantrę, że kiedy ktoś pyta o coś, odpowiedź jest udzielana ... wraz z myślą „czy to powinno być na wiki po raz kolejny ktoś pyta?”