Przebywając w świecie IT można się nasłuchać mnóstwa historii o słabych dokumentacjach jakiegoś oprogramowania. Nawet się do tego przyzwyczailiśmy, że im droższy program albo biblioteka tym gorzej z dokumentacją. Ma to jakiś sens w przypadku firm, które mają maksymalnie kilka produktów i jednocześnie oferują płatne wsparcie techniczne i wdrożenie jakiegoś narzędzia. Jednak gorzej jeżeli taka sytuacja występuje w przypadku dużo większych graczy. Takich, którzy dostarczają narzędzia, które są tylko bazą do czegoś większego. Chociażby taka dosyć znana firma Microsoft. Większość produktów jakie oferują, takich jak systemy operacyjne, biblioteki, języki czy w końcu infrastruktura są tylko bazą dla innych rozwiązań innych firm. Wydawało mi się więc, że w takim przypadku powinno im zależeć na tym żeby ich rozwiązania były przyjemne w użyciu, a więc chętniej wykorzystywane w innych usługach. Ale im bardziej zagłębiam się w produkty Microsoftu tym bardziej oddalam się od stwierdzenia, że są przyjemne w użyciu.

Na początku jest w porządku

Jeżeli chodzi o podstawy programowania z użyciem ich technologii to Microsoft ma co najmniej dobrą dokumentację (tylko trzeba przełączyć na język angielski bo automatyczne tłumaczenia to koszmar). Podstawy C# czy biblioteki standardowej .NET są opisane przystępnie i posiadają dużo przykładów. Problem zaczyna się robić jeżeli przeskoczymy ten etap.

Moje pierwsze problemy z dokumentacją narzędzi Microsoftu pojawiły się chyba w momencie kiedy chciałem skorzystać z Azure. Podstawy o tym jak coś uruchomić w samej usłudze są w miarę przystępnie opisane. Jednak kiedy potrzebowałem połączyć ze sobą kilka usług albo spiąć TFSa z Azurem to robiły się schody. Wszystko co wykraczało poza najprostszą ścieżkę było nieudokumentowane. A najprostsza ścieżka to ta, która nie sprawdza się realnych zastosowaniach. Z resztą moje obserwacje potwierdzają koledzy z pracy. W jednym z projektów musieli zintegrować się z Service Busem w Azure. Większość pracy polegała na rozwiązywaniu pojawiających się problemów metodą prób i błędów. Przy stawianiu środowisk u obecnego klienta sytuacja wyglądała jeszcze „ciekawiej” bo z opowieści wynika, że wdrożenie continuous delivery w TFSie z wykorzystaniem Dockera to jak chodzenie po nowym mieście bez mapy i drogowskazów. Trzeba pytać innych użytkowników drogi i liczyć, że byli już w miejscu, do którego dążymy. Bo samo miasto nie zapewniło informacji jak tam można dotrzeć.

Chcesz coś osiągnąć? A po co?

I właśnie z TFSem zderzyłem się w ostatnim tygodniu. Ponieważ trafiła mi się mała przerwa pomiędzy projektami to postanowiłem poruszyć temat, który mamy gdzieś na tablicy od dłuższego czasu. Chodzi o generowanie changeloga przy wypuszczaniu kolejnych wersji projektu. Chcieliśmy mieć rozwiązanie skrojone na nasze potrzeby i minimalizujące biurokrację z instalowanie i zarządzeniem jakimiś dodatkami do TFSa właśnie. Dlatego mając chwilę czasu postanowiłem przyjrzeć się tematowi. I przekonałem się, że ostatnim miejscem gdzie cokolwiek znajdę jest strona producenta.

Microsoft dostarcza bibliotekę .NET, która pozwala łączyć się z TFSem (np. pobierać listę zadań czy tworzyć buildy). Jednak zapomniał powiedzieć jak je używać. Szukając nawet takich podstaw jak to w jaki sposób połączyć się z TFSem jedyne wartościowe źródła to były blogi i odpowiedzi na StackOverflow. Jednak nawet w tym przypadku trzeba było zebrać wiadomości z kilku źródeł żeby dostać interesującą mnie informację. Za to informacje jakie dostarcza nam Microsoft to… lista klas i metod. Czyli jedynie co zrobił to wygenerował dokument z tego co ma w kodzie. Nawet zdania opisujące te klasy i metody są takie same jak podpowiada nam IDE przy korzystaniu z nich.

No dobra, jest kilka sampli. Jednak poza samym kodem z kilkoma komentarzami nie ma w nich za wiele. Trzeba się domyślać co jest czym. Jeszcze większa tragedia jest jeżeli ktoś chce użyć WIQL czyli takiego języka zapytań pozwalającego zbudować query, które pobierze nam dokładnie takie work itemy jakich potrzebujemy. Poza kilkoma gotowymi zapytaniami znalezionymi w przykładach nie znalazłem absolutnie żadnej dokumentacji do tego. Po kilku dniach poszukiwań nadal nie wiem jakie tabele są dostępne i jak najlepiej budować takie zapytania. Więc uznaję to za metodę nieużywalną w realnym programie. W tym wypadku nawet StackOverflow nie posiada informacji na ten temat.

Nie można lepiej?

Dlaczego nie można lepiej? Nie potrzebuję przecież mieć tłumaczonych dokumentacji na 150 języków świata. Wystarczy coś po angielsku. Ludzie zadają mnóstwo pytań na forach. Ale nie ma na nie oficjalnych odpowiedzi. A mówimy tutaj o produktach skierowanych do programistów. A programista zanim uzna, że coś jest dobre to sprawdzi jak tego użyć i czy w razie problemów znajdzie wystarczająco dużo materiałów. Tutaj nie da się wciskać produktu ładną reklamą. Bo najlepszą reklamą dla produktów skierowanych do programistów jest przejrzystość dokumentacji i łatwość znalezienia informacji „jak zacząć” i gdzie szukać dalej.

I właśnie takich dokumentacji Wam wszystkim życzę w tą niedzielę – przystępnych i kompletnych.